1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year><year>2022</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>global</title>
<prepared>Martin Björklund</prepared>
<docno></docno>
<date>1997-11-17</date>
<rev></rev>
</header>
<module since="">global</module>
<modulesummary>A global name registration facility.</modulesummary>
<description>
<p>This module consists of the following services:</p>
<list type="bulleted">
<item>Registration of global names</item>
<item>Global locks</item>
<item>Maintenance of the fully connected network</item>
</list>
<marker id="prevent_overlapping_partitions"/>
<p>
As of OTP 25, <c>global</c> will by default prevent overlapping
partitions due to network issues by actively disconnecting from
nodes that reports that they have lost connections to other
nodes. This will cause fully connected partitions to form instead
of leaving the network in a state with overlapping partitions.
</p>
<warning>
<p>
Prevention of overlapping partitions can be disabled using the
<seeapp marker="kernel_app#prevent_overlapping_partitions">
<c>prevent_overlapping_partitions</c></seeapp>
<c>kernel(6)</c> parameter, making <c>global</c>
behave like it used to do. This is, however, problematic for all
applications expecting a fully connected network to be provided,
such as for example <c>mnesia</c>, but also for <c>global</c> itself.
A network of overlapping partitions might cause the internal state of
<c>global</c> to become inconsistent. Such an inconsistency can
remain even after such partitions have been brought together to form
a fully connected network again. The effect on other applications
that expects that a fully connected network is maintained may vary,
but they might misbehave in very subtle hard to detect ways during
such a partitioning. Since you might get hard to detect issues without
this fix, you are <i>strongly</i> advised <i>not</i> to disable this
fix. Also note that this fix <i>has</i> to be enabled on <i>all</i>
nodes in the network in order to work properly.
</p>
</warning>
<note>
<p>
None of the above services will be reliably delivered unless both of
the kernel parameters
<seeapp marker="kernel_app#connect_all"><c>connect_all</c></seeapp>
and <seeapp marker="kernel_app#prevent_overlapping_partitions">
<c>prevent_overlapping_partitions</c></seeapp> are enabled. Calls to
the <c>global</c> API will, however, <i>not</i> fail even though one or
both of them are disabled. You will just get unreliable results.
</p>
</note>
<p>These services are controlled through the process
<c>global_name_server</c> that exists on every node. The global
name server starts automatically when a node is started.
With the term <em>global</em> is meant over a system consisting
of many Erlang nodes.</p>
<p>The ability to globally register names is a central concept in
the programming of distributed Erlang systems. In this module,
the equivalent of the <c>register/2</c> and <c>whereis/1</c>
BIFs (for local name registration) are provided, but for a
network of Erlang nodes. A registered name is an alias for a
process identifier (pid). The global name server monitors
globally registered pids. If a process terminates, the name is
also globally unregistered.</p>
<p>The registered names are stored in replica global name tables on
every node. There is no central storage point. Thus,
the translation of a name to a pid is fast, as it is always done
locally. For any action resulting in a change to the global name table,
all tables on other nodes are automatically updated.</p>
<p>Global locks have lock identities and are set on a specific
resource. For example, the specified resource can be a pid.
When a global lock is set, access to the locked resource is
denied for all resources other than the lock requester.</p>
<p>Both the registration and lock services are atomic.
All nodes involved in these actions have the same view of
the information.</p>
<p>The global name server also performs the critical task of
continuously monitoring changes in node configuration. If a node
that runs a globally registered process goes down, the name
is globally unregistered. To this end, the global name
server subscribes to <c>nodeup</c> and <c>nodedown</c> messages
sent from module <c>net_kernel</c>. Relevant Kernel
application variables in this context are <c>net_setuptime</c>,
<c>net_ticktime</c>, and <c>dist_auto_connect</c>. See also
<seeapp marker="kernel_app#net_setuptime"><c>kernel(6)</c></seeapp>.</p>
<p>The name server also maintains a fully connected network. For
example, if node <c>N1</c> connects to node <c>N2</c> (which is
already connected to <c>N3</c>), the global name servers on the
nodes <c>N1</c> and <c>N3</c> ensure that also <c>N1</c>
and <c>N3</c> are connected.
In this case, the name registration service cannot be used, but the
lock mechanism still works.</p>
<p>If the global name server fails to connect nodes (<c>N1</c> and
<c>N3</c> in the example), a warning event is sent to the
error logger. The presence of such an event does not exclude the
nodes to connect later (you can, for
example, try command <c>rpc:call(N1, net_adm, ping, [N2])</c> in
the Erlang shell), but it indicates a network problem.</p>
<note>
<p>If the fully connected network is not set up properly, try
first to increase the value of <c>net_setuptime</c>.</p>
</note>
</description>
<datatypes>
<datatype>
<name name="id"/>
</datatype>
</datatypes>
<funcs>
<func>
<name name="del_lock" arity="1" since=""/>
<name name="del_lock" arity="2" since=""/>
<fsummary>Delete a lock.</fsummary>
<desc>
<p>Deletes the lock <c><anno>Id</anno></c> synchronously.</p>
</desc>
</func>
<func>
<name name="disconnect" arity="0" since="OTP 25.1"/>
<fsummary>Disconnect from all other nodes known to global</fsummary>
<desc>
<p>
Disconnect from all other nodes known to <c>global</c>. A list
of node names (in an unspecified order) is returned which corresponds
to the nodes that were disconnected. All disconnect operations
performed have completed when <c>global:disconnect/0</c> returns.
</p>
<p>
The disconnects will be made in such a way that only the current
node will be removed from the cluster of <c>global</c> nodes. If
<seeerl marker="#prevent_overlapping_partitions">
<c>prevent_overlapping_partitions</c></seeerl> is enabled and
you disconnect, from other nodes in the cluster of <c>global</c>
nodes, by other means, <c>global</c> on the other nodes may
partition the remaining nodes in order to ensure that no
overlapping partitions appear. Even if
<c>prevent_overlapping_partitions</c> is disabled, you should
preferably use <c>global:disconnect/0</c> in order to remove
current node from a cluster of <c>global</c> nodes, since you
otherwise likely <em>will</em> create overlapping partitions which
might <seeerl marker="#prevent_overlapping_partitions">cause
problems</seeerl>.
</p>
<p>
Note that if the node is going to be halted, there is <em>no</em>
need to remove it from a cluster of <c>global</c> nodes explicitly by
calling <c>global:disconnect/0</c> before halting it. The removal
from the cluster is taken care of automatically when the node
halts regardless of whether <c>prevent_overlapping_partitions</c> is
enabled or not.
</p>
<p>
If current node has been configured to be part of a
<seeerl marker="global_group"><i>global group</i></seeerl>, only
connected and/or synchronized nodes in that group are known to
<c>global</c>, so <c>global:disconnect/0</c> will <em>only</em>
disconnect from those nodes. If current node is <em>not</em> part of
a <i>global group</i>, all
<seemfa marker="erts:erlang#nodes/0">connected visible nodes</seemfa>
will be known to <c>global</c>, so <c>global:disconnect/0</c> will
disconnect from all those nodes.
</p>
<p>
Note that information about connected nodes does not instantaneously
reach <c>global</c>, so the caller might see a node part of the
result returned by
<seemfa marker="erts:erlang#nodes/0"><c>nodes()</c></seemfa> while
it still is not known to <c>global</c>. The disconnect operation
will, however, still not cause any overlapping partitions when
<c>prevent_overlapping_partitions</c> is enabled. If
<c>prevent_overlapping_partitions</c> is disabled, overlapping
partitions might form in this case.
</p>
<p>
Note that when <c>prevent_overlapping_partitions</c> is enabled,
you may see warning reports on other nodes when they detect that
current node has disconnected. These are in this case completely
harmless and can be ignored.
</p>
</desc>
</func>
<func>
<name name="notify_all_name" arity="3" since=""/>
<fsummary>Name resolving function that notifies both pids.</fsummary>
<desc>
<p>Can be used as a name resolving function for
<seemfa marker="#register_name/3"><c>register_name/3</c></seemfa>
and
<seemfa marker="#re_register_name/3"><c>re_register_name/3</c></seemfa>.</p>
<p>The function unregisters both pids and sends the message
<c>{global_name_conflict, <anno>Name</anno>, OtherPid}</c> to both
processes.</p>
</desc>
</func>
<func>
<name name="random_exit_name" arity="3" since=""/>
<fsummary>Name resolving function that kills one pid.</fsummary>
<desc>
<p>Can be used as a name resolving function for
<seemfa marker="#register_name/3"><c>register_name/3</c></seemfa>
and
<seemfa marker="#re_register_name/3"><c>re_register_name/3</c></seemfa>.</p>
<p>The function randomly selects one of the pids for registration and
kills the other one.</p>
</desc>
</func>
<func>
<name name="random_notify_name" arity="3" since=""/>
<fsummary>Name resolving function that notifies one pid.</fsummary>
<desc>
<p>Can be used as a name resolving function for
<seemfa marker="#register_name/3"><c>register_name/3</c></seemfa>
and
<seemfa marker="#re_register_name/3"><c>re_register_name/3</c></seemfa>.</p>
<p>The function randomly selects one of the pids for registration, and
sends the message <c>{global_name_conflict, <anno>Name</anno>}</c> to
the other pid.</p>
</desc>
</func>
<func>
<name name="re_register_name" arity="2" since=""/>
<name name="re_register_name" arity="3" since=""/>
<fsummary>Atomically re-register a name.</fsummary>
<type name="method"/>
<type_desc name="method">{<c>Module</c>, <c>Function</c>}
is also allowed.
</type_desc>
<desc>
<p>Atomically changes the registered name <c><anno>Name</anno></c> on
all nodes to refer to <c><anno>Pid</anno></c>.</p>
<p>Function <c><anno>Resolve</anno></c> has the same behavior as in
<seemfa marker="#register_name/2"><c>register_name/2,3</c></seemfa>.
</p>
</desc>
</func>
<func>
<name name="register_name" arity="2" since=""/>
<name name="register_name" arity="3" since=""/>
<fsummary>Globally register a name for a pid.</fsummary>
<type name="method"/>
<type_desc name="method">{<c>Module</c>, <c>Function</c>} is also
allowed for backward compatibility, but its use is deprecated.
</type_desc>
<desc>
<p>Globally associates name <c><anno>Name</anno></c> with a pid, that
is, globally notifies all nodes of a new global name in a network
of Erlang nodes.</p>
<p>When new nodes are added to the network, they are informed
of the globally registered names that already exist.
The network is also informed of any global names in newly
connected nodes. If any name clashes are discovered,
function <c><anno>Resolve</anno></c> is called. Its purpose is to
decide which pid is correct. If the function crashes, or
returns anything other than one of the pids, the name is
unregistered. This function is called once for each name
clash.</p>
<warning>
<p>If you plan to change code without restarting your system,
you must use an external fun (<c>fun Module:Function/Arity</c>)
as function <c><anno>Resolve</anno></c>. If you use a
local fun, you can never replace the code for the module that
the fun belongs to.</p>
</warning>
<p>Three predefined resolve functions exist:
<c>random_exit_name/3</c>, <c>random_notify_name/3</c>, and
<c>notify_all_name/3</c>. If no <c><anno>Resolve</anno></c> function
is defined, <c>random_exit_name</c> is used. This means that one
of the two registered processes is selected as correct
while the other is killed.</p>
<p>This function is completely synchronous, that is,
when this function returns, the name is either registered on
all nodes or none.</p>
<p>The function returns <c>yes</c> if successful, <c>no</c> if
it fails. For example, <c>no</c> is returned if an attempt
is made to register an already registered process or to
register a process with a name that is already in use.</p>
<note>
<p>Releases up to and including Erlang/OTP R10 did not check if the
process was already registered. The global name table could
therefore become inconsistent. The old
(buggy) behavior can be chosen by giving the Kernel
application variable <c>global_multi_name_action</c> the
value <c>allow</c>.</p>
</note>
<p>If a process with a registered name dies, or the node goes
down, the name is unregistered on all nodes.</p>
</desc>
</func>
<func>
<name name="registered_names" arity="0" since=""/>
<fsummary>All globally registered names.</fsummary>
<desc>
<p>Returns a list of all globally registered names.</p>
</desc>
</func>
<func>
<name name="send" arity="2" since=""/>
<fsummary>Send a message to a globally registered pid.</fsummary>
<desc>
<p>Sends message <c><anno>Msg</anno></c> to the pid globally registered
as <c><anno>Name</anno></c>.</p>
<p>If <c><anno>Name</anno></c> is not a globally registered
name, the calling function exits with reason
<c>{badarg, {<anno>Name</anno>, <anno>Msg</anno>}}</c>.</p>
</desc>
</func>
<func>
<name name="set_lock" arity="1" since=""/>
<name name="set_lock" arity="2" since=""/>
<name name="set_lock" arity="3" since=""/>
<fsummary>Set a lock on the specified nodes.</fsummary>
<type name="id"/>
<type name="retries"/>
<desc>
<p>Sets a lock on the specified nodes (or on all nodes if none
are specified) on <c><anno>ResourceId</anno></c> for
<c><anno>LockRequesterId</anno></c>. If a lock already exists on
<c><anno>ResourceId</anno></c> for another requester than
<c><anno>LockRequesterId</anno></c>, and <c><anno>Retries</anno></c>
is not equal to <c>0</c>, the process sleeps for a while and tries
to execute the action later. When <c><anno>Retries</anno></c>
attempts have been made, <c>false</c> is returned, otherwise
<c>true</c>. If <c><anno>Retries</anno></c> is <c>infinity</c>,
<c>true</c> is eventually returned (unless the lock is never
released).</p>
<p>If no value for <c><anno>Retries</anno></c> is specified,
<c>infinity</c> is used.</p>
<p>This function is completely synchronous.</p>
<p>If a process that holds a lock dies, or the node goes
down, the locks held by the process are deleted.</p>
<p>The global name server keeps track of all processes sharing
the same lock, that is, if two processes set the same lock,
both processes must delete the lock.</p>
<p>This function does not address the problem of a deadlock. A
deadlock can never occur as long as processes only lock one
resource at a time. A deadlock can occur if some processes
try to lock two or more resources. It is up to the
application to detect and rectify a deadlock.</p>
<note>
<p>Avoid the following values of <c><anno>ResourceId</anno></c>,
otherwise Erlang/OTP does not work properly:</p>
<list type="bulleted">
<item><c>dist_ac</c></item>
<item><c>global</c></item>
<item><c>mnesia_adjust_log_writes</c></item>
<item><c>mnesia_table_lock</c></item>
</list>
</note>
</desc>
</func>
<func>
<name name="sync" arity="0" since=""/>
<fsummary>Synchronize the global name server.</fsummary>
<desc>
<p>Synchronizes the global name server with all nodes known to
this node. These are the nodes that are returned from
<c>erlang:nodes()</c>. When this function returns,
the global name server receives global information from
all nodes. This function can be called when new nodes are
added to the network.</p>
<p>The only possible error reason <c>Reason</c> is
<c>{"global_groups definition error", Error}</c>.</p>
</desc>
</func>
<func>
<name name="trans" arity="2" since=""/>
<name name="trans" arity="3" since=""/>
<name name="trans" arity="4" since=""/>
<fsummary>Micro transaction facility.</fsummary>
<type name="retries"/>
<type name="trans_fun"/>
<desc>
<p>Sets a lock on <c><anno>Id</anno></c> (using
<seemfa marker="#set_lock/3"><c>set_lock/3</c></seemfa>).
If this succeeds, <c><anno>Fun</anno>()</c> is evaluated and the
result <c><anno>Res</anno></c>
is returned. Returns <c>aborted</c> if the lock attempt fails.
If <c><anno>Retries</anno></c> is set to <c>infinity</c>,
the transaction does not abort.</p>
<p><c>infinity</c> is the default setting and is used if
no value is specified for <c><anno>Retries</anno></c>.</p>
</desc>
</func>
<func>
<name name="unregister_name" arity="1" since=""/>
<fsummary>Remove a globally registered name for a pid.</fsummary>
<desc>
<p>Removes the globally registered name <c><anno>Name</anno></c> from
the network of Erlang nodes.</p>
</desc>
</func>
<func>
<name name="whereis_name" arity="1" since=""/>
<fsummary>Get the pid with a specified globally registered name.</fsummary>
<desc>
<p>Returns the pid with the globally registered name
<c><anno>Name</anno></c>. Returns <c>undefined</c> if the name is not
globally registered.</p>
</desc>
</func>
</funcs>
<section>
<title>See Also</title>
<p><seeerl marker="global_group"><c>global_group(3)</c></seeerl>,
<seeerl marker="net_kernel"><c>net_kernel(3)</c></seeerl></p>
</section>
</erlref>
|