1global(3)                  Erlang Module Definition                  global(3)
2
3
4

NAME

6       global - A global name registration facility.
7

DESCRIPTION

9       This module consists of the following services:
10
11         * Registration of global names
12
13         * Global locks
14
15         * Maintenance of the fully connected network
16
17       As of OTP 25, global will by default prevent overlapping partitions due
18       to network issues by actively disconnecting  from  nodes  that  reports
19       that  they  have lost connections to other nodes. This will cause fully
20       connected partitions to form instead of leaving the network in a  state
21       with overlapping partitions.
22
23   Warning:
24       Prevention  of  overlapping  partitions  can be disabled using the pre‐
25       vent_overlapping_partitions kernel(6) parameter, making  global  behave
26       like  it used to do. This is, however, problematic for all applications
27       expecting a fully connected network to be provided, such as for example
28       mnesia, but also for global itself. A network of overlapping partitions
29       might cause the internal state of global to become  inconsistent.  Such
30       an  inconsistency  can  remain  even  after  such  partitions have been
31       brought together to form a fully connected network again. The effect on
32       other applications that expects that a fully connected network is main‐
33       tained may vary, but they might misbehave in very subtle hard to detect
34       ways during such a partitioning. Since you might get hard to detect is‐
35       sues without this fix, you are strongly  advised not  to  disable  this
36       fix.  Also  note  that this fix has  to be enabled on all  nodes in the
37       network in order to work properly.
38
39
40   Note:
41       None of the above services will be reliably delivered  unless  both  of
42       the  kernel  parameters  connect_all and prevent_overlapping_partitions
43       are enabled. Calls to the global API  will,  however,  not   fail  even
44       though  one  or both of them are disabled. You will just get unreliable
45       results.
46
47
48       These services are controlled through  the  process  global_name_server
49       that  exists on every node. The global name server starts automatically
50       when a node is started. With the term global is  meant  over  a  system
51       consisting of many Erlang nodes.
52
53       The ability to globally register names is a central concept in the pro‐
54       gramming of distributed Erlang systems. In this module, the  equivalent
55       of  the register/2 and whereis/1 BIFs (for local name registration) are
56       provided, but for a network of Erlang nodes. A registered  name  is  an
57       alias  for  a process identifier (pid). The global name server monitors
58       globally registered pids. If a process terminates,  the  name  is  also
59       globally unregistered.
60
61       The  registered names are stored in replica global name tables on every
62       node. There is no central storage point. Thus,  the  translation  of  a
63       name to a pid is fast, as it is always done locally. For any action re‐
64       sulting in a change to the global name table, all tables on other nodes
65       are automatically updated.
66
67       Global  locks  have lock identities and are set on a specific resource.
68       For example, the specified resource can be a pid. When a global lock is
69       set,  access  to  the locked resource is denied for all resources other
70       than the lock requester.
71
72       Both the registration and lock services are atomic. All nodes  involved
73       in these actions have the same view of the information.
74
75       The  global name server also performs the critical task of continuously
76       monitoring changes in node configuration. If a node that runs  a  glob‐
77       ally  registered  process goes down, the name is globally unregistered.
78       To this end, the global name server subscribes to nodeup  and  nodedown
79       messages sent from module net_kernel. Relevant Kernel application vari‐
80       ables  in   this   context   are   net_setuptime,   net_ticktime,   and
81       dist_auto_connect. See also kernel(6).
82
83       The  name server also maintains a fully connected network. For example,
84       if node N1 connects to node N2 (which is already connected to N3),  the
85       global  name  servers on the nodes N1 and N3 ensure that also N1 and N3
86       are connected. In this case, the name registration  service  cannot  be
87       used, but the lock mechanism still works.
88
89       If  the global name server fails to connect nodes (N1 and N3 in the ex‐
90       ample), a warning event is sent to the error logger.  The  presence  of
91       such an event does not exclude the nodes to connect later (you can, for
92       example, try command rpc:call(N1, net_adm, ping, [N2])  in  the  Erlang
93       shell), but it indicates a network problem.
94
95   Note:
96       If the fully connected network is not set up properly, try first to in‐
97       crease the value of net_setuptime.
98
99

DATA TYPES

101       id() = {ResourceId :: term(), LockRequesterId :: term()}
102

EXPORTS

104       del_lock(Id) -> true
105
106       del_lock(Id, Nodes) -> true
107
108              Types:
109
110                 Id = id()
111                 Nodes = [node()]
112
113              Deletes the lock Id synchronously.
114
115       disconnect() -> [node()]
116
117              Disconnect from all other nodes known to global. A list of  node
118              names (in an unspecified order) is returned which corresponds to
119              the nodes that were disconnected. All disconnect operations per‐
120              formed have completed when global:disconnect/0 returns.
121
122              The disconnects will be made in such a way that only the current
123              node will be removed from the cluster of global nodes.  If  pre‐
124              vent_overlapping_partitions  is enabled and you disconnect, from
125              other nodes in the cluster of  global  nodes,  by  other  means,
126              global  on  the other nodes may partition the remaining nodes in
127              order to ensure that no overlapping partitions appear.  Even  if
128              prevent_overlapping_partitions  is  disabled, you should prefer‐
129              ably use global:disconnect/0 in order  to  remove  current  node
130              from  a cluster of global nodes, since you otherwise likely will
131              create overlapping partitions which might cause problems.
132
133              Note that if the node is going to be halted, there is no need to
134              remove  it  from a cluster of global nodes explicitly by calling
135              global:disconnect/0 before halting  it.  The  removal  from  the
136              cluster  is  taken care of automatically when the node halts re‐
137              gardless of whether prevent_overlapping_partitions is enabled or
138              not.
139
140              If current node has been configured to be part of a global group
141              , only connected and/or synchronized nodes  in  that  group  are
142              known  to  global,  so  global:disconnect/0 will only disconnect
143              from those nodes. If current node is not part of a global  group
144              ,  all  connected  visible  nodes  will  be  known to global, so
145              global:disconnect/0 will disconnect from all those nodes.
146
147              Note that information about connected nodes does  not  instanta‐
148              neously reach global, so the caller might see a node part of the
149              result returned by nodes()  while  it  still  is  not  known  to
150              global.  The disconnect operation will, however, still not cause
151              any overlapping partitions  when  prevent_overlapping_partitions
152              is enabled. If prevent_overlapping_partitions is disabled, over‐
153              lapping partitions might form in this case.
154
155              Note that when prevent_overlapping_partitions  is  enabled,  you
156              may  see  warning  reports  on other nodes when they detect that
157              current node has disconnected. These are in this case completely
158              harmless and can be ignored.
159
160       notify_all_name(Name, Pid1, Pid2) -> none
161
162              Types:
163
164                 Name = term()
165                 Pid1 = Pid2 = pid()
166
167              Can be used as a name resolving function for register_name/3 and
168              re_register_name/3.
169
170              The  function  unregisters  both  pids  and  sends  the  message
171              {global_name_conflict, Name, OtherPid} to both processes.
172
173       random_exit_name(Name, Pid1, Pid2) -> pid()
174
175              Types:
176
177                 Name = term()
178                 Pid1 = Pid2 = pid()
179
180              Can be used as a name resolving function for register_name/3 and
181              re_register_name/3.
182
183              The function randomly selects one of the pids  for  registration
184              and kills the other one.
185
186       random_notify_name(Name, Pid1, Pid2) -> pid()
187
188              Types:
189
190                 Name = term()
191                 Pid1 = Pid2 = pid()
192
193              Can be used as a name resolving function for register_name/3 and
194              re_register_name/3.
195
196              The function randomly selects one of the pids for  registration,
197              and  sends the message {global_name_conflict, Name} to the other
198              pid.
199
200       re_register_name(Name, Pid) -> yes
201
202       re_register_name(Name, Pid, Resolve) -> yes
203
204              Types:
205
206                 Name = term()
207                 Pid = pid()
208                 Resolve = method()
209                 method() =
210                     fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
211                             pid() | none)
212                   {Module, Function} is also allowed.
213
214              Atomically changes the registered name Name on all nodes to  re‐
215              fer to Pid.
216
217              Function Resolve has the same behavior as in register_name/2,3.
218
219       register_name(Name, Pid) -> yes | no
220
221       register_name(Name, Pid, Resolve) -> yes | no
222
223              Types:
224
225                 Name = term()
226                 Pid = pid()
227                 Resolve = method()
228                 method() =
229                     fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
230                             pid() | none)
231                   {Module, Function} is also allowed for backward compatibil‐
232                   ity, but its use is deprecated.
233
234              Globally associates name Name with a pid, that is, globally  no‐
235              tifies  all  nodes  of  a new global name in a network of Erlang
236              nodes.
237
238              When new nodes are added to the network, they  are  informed  of
239              the globally registered names that already exist. The network is
240              also informed of any global names in newly connected  nodes.  If
241              any name clashes are discovered, function Resolve is called. Its
242              purpose is to decide which  pid  is  correct.  If  the  function
243              crashes,  or  returns  anything  other than one of the pids, the
244              name is unregistered. This function is called once for each name
245              clash.
246
247          Warning:
248              If  you  plan to change code without restarting your system, you
249              must use an external fun (fun Module:Function/Arity) as function
250              Resolve.  If you use a local fun, you can never replace the code
251              for the module that the fun belongs to.
252
253
254              Three predefined resolve  functions  exist:  random_exit_name/3,
255              random_notify_name/3, and notify_all_name/3. If no Resolve func‐
256              tion is defined, random_exit_name is used. This means  that  one
257              of the two registered processes is selected as correct while the
258              other is killed.
259
260              This function is completely  synchronous,  that  is,  when  this
261              function  returns, the name is either registered on all nodes or
262              none.
263
264              The function returns yes if successful, no if it fails. For  ex‐
265              ample,  no  is returned if an attempt is made to register an al‐
266              ready registered process or to register a process  with  a  name
267              that is already in use.
268
269          Note:
270              Releases up to and including Erlang/OTP R10 did not check if the
271              process was already registered.  The  global  name  table  could
272              therefore  become  inconsistent. The old (buggy) behavior can be
273              chosen   by   giving    the    Kernel    application    variable
274              global_multi_name_action the value allow.
275
276
277              If a process with a registered name dies, or the node goes down,
278              the name is unregistered on all nodes.
279
280       registered_names() -> [Name]
281
282              Types:
283
284                 Name = term()
285
286              Returns a list of all globally registered names.
287
288       send(Name, Msg) -> Pid
289
290              Types:
291
292                 Name = Msg = term()
293                 Pid = pid()
294
295              Sends message Msg to the pid globally registered as Name.
296
297              If Name is not a globally registered name, the calling  function
298              exits with reason {badarg, {Name, Msg}}.
299
300       set_lock(Id) -> boolean()
301
302       set_lock(Id, Nodes) -> boolean()
303
304       set_lock(Id, Nodes, Retries) -> boolean()
305
306              Types:
307
308                 Id = id()
309                 Nodes = [node()]
310                 Retries = retries()
311                 id() = {ResourceId :: term(), LockRequesterId :: term()}
312                 retries() = integer() >= 0 | infinity
313
314              Sets  a lock on the specified nodes (or on all nodes if none are
315              specified) on ResourceId for LockRequesterId. If a lock  already
316              exists on ResourceId for another requester than LockRequesterId,
317              and Retries is not equal to 0, the process sleeps  for  a  while
318              and  tries  to  execute  the action later. When Retries attempts
319              have been made, false is returned, otherwise true. If Retries is
320              infinity,  true is eventually returned (unless the lock is never
321              released).
322
323              If no value for Retries is specified, infinity is used.
324
325              This function is completely synchronous.
326
327              If a process that holds a lock dies, or the node goes down,  the
328              locks held by the process are deleted.
329
330              The  global name server keeps track of all processes sharing the
331              same lock, that is, if two processes set  the  same  lock,  both
332              processes must delete the lock.
333
334              This  function  does  not  address  the problem of a deadlock. A
335              deadlock can never occur as long as processes only lock one  re‐
336              source  at a time. A deadlock can occur if some processes try to
337              lock two or more resources. It is up to the application  to  de‐
338              tect and rectify a deadlock.
339
340          Note:
341              Avoid  the  following values of ResourceId, otherwise Erlang/OTP
342              does not work properly:
343
344                * dist_ac
345
346                * global
347
348                * mnesia_adjust_log_writes
349
350                * mnesia_table_lock
351
352       sync() -> ok | {error, Reason :: term()}
353
354              Synchronizes the global name server with all nodes known to this
355              node. These are the nodes that are returned from erlang:nodes().
356              When this function returns,  the  global  name  server  receives
357              global  information  from all nodes. This function can be called
358              when new nodes are added to the network.
359
360              The only possible error reason Reason is {"global_groups defini‐
361              tion error", Error}.
362
363       trans(Id, Fun) -> Res | aborted
364
365       trans(Id, Fun, Nodes) -> Res | aborted
366
367       trans(Id, Fun, Nodes, Retries) -> Res | aborted
368
369              Types:
370
371                 Id = id()
372                 Fun = trans_fun()
373                 Nodes = [node()]
374                 Retries = retries()
375                 Res = term()
376                 retries() = integer() >= 0 | infinity
377                 trans_fun() = function() | {module(), atom()}
378
379              Sets a lock on Id (using set_lock/3). If this succeeds, Fun() is
380              evaluated and the result Res is returned. Returns aborted if the
381              lock  attempt fails. If Retries is set to infinity, the transac‐
382              tion does not abort.
383
384              infinity is the default setting and is used if no value is spec‐
385              ified for Retries.
386
387       unregister_name(Name) -> term()
388
389              Types:
390
391                 Name = term()
392
393              Removes  the  globally  registered name Name from the network of
394              Erlang nodes.
395
396       whereis_name(Name) -> pid() | undefined
397
398              Types:
399
400                 Name = term()
401
402              Returns the pid with the globally registered name Name.  Returns
403              undefined if the name is not globally registered.
404

SEE ALSO

406       global_group(3), net_kernel(3)
407
408
409
410Ericsson AB                     kernel 8.5.4.2                       global(3)
Impressum