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       These  services  are  controlled through the process global_name_server
18       that exists on every node. The global name server starts  automatically
19       when  a  node  is  started. With the term global is meant over a system
20       consisting of many Erlang nodes.
21
22       The ability to globally register names is a central concept in the pro‐
23       gramming  of distributed Erlang systems. In this module, the equivalent
24       of the register/2 and whereis/1 BIFs (for local name registration)  are
25       provided,  but  for  a network of Erlang nodes. A registered name is an
26       alias for a process identifier (pid). The global name  server  monitors
27       globally  registered  pids.  If  a process terminates, the name is also
28       globally unregistered.
29
30       The registered names are stored in replica global name tables on  every
31       node.  There  is  no  central storage point. Thus, the translation of a
32       name to a pid is fast, as it is always done locally. For any action re‐
33       sulting in a change to the global name table, all tables on other nodes
34       are automatically updated.
35
36       Global locks have lock identities and are set on a  specific  resource.
37       For example, the specified resource can be a pid. When a global lock is
38       set, access to the locked resource is denied for  all  resources  other
39       than the lock requester.
40
41       Both  the registration and lock services are atomic. All nodes involved
42       in these actions have the same view of the information.
43
44       The global name server also performs the critical task of  continuously
45       monitoring  changes  in node configuration. If a node that runs a glob‐
46       ally registered process goes down, the name is  globally  unregistered.
47       To  this  end, the global name server subscribes to nodeup and nodedown
48       messages sent from module net_kernel. Relevant Kernel application vari‐
49       ables   in   this   context   are   net_setuptime,   net_ticktime,  and
50       dist_auto_connect. See also kernel(6).
51
52       The name server also maintains a fully connected network. For  example,
53       if  node N1 connects to node N2 (which is already connected to N3), the
54       global name servers on the nodes N1 and N3 ensure that also N1  and  N3
55       are  connected.  If this is not desired, command-line flag -connect_all
56       false can be used (see also erl(1)). In this case, the  name  registra‐
57       tion service cannot be used, but the lock mechanism still works.
58
59       If  the global name server fails to connect nodes (N1 and N3 in the ex‐
60       ample), a warning event is sent to the error logger.  The  presence  of
61       such an event does not exclude the nodes to connect later (you can, for
62       example, try command rpc:call(N1, net_adm, ping, [N2])  in  the  Erlang
63       shell), but it indicates a network problem.
64
65   Note:
66       If the fully connected network is not set up properly, try first to in‐
67       crease the value of net_setuptime.
68
69

DATA TYPES

71       id() = {ResourceId :: term(), LockRequesterId :: term()}
72

EXPORTS

74       del_lock(Id) -> true
75
76       del_lock(Id, Nodes) -> true
77
78              Types:
79
80                 Id = id()
81                 Nodes = [node()]
82
83              Deletes the lock Id synchronously.
84
85       notify_all_name(Name, Pid1, Pid2) -> none
86
87              Types:
88
89                 Name = term()
90                 Pid1 = Pid2 = pid()
91
92              Can be used as a name resolving function for register_name/3 and
93              re_register_name/3.
94
95              The  function  unregisters  both  pids  and  sends  the  message
96              {global_name_conflict, Name, OtherPid} to both processes.
97
98       random_exit_name(Name, Pid1, Pid2) -> pid()
99
100              Types:
101
102                 Name = term()
103                 Pid1 = Pid2 = pid()
104
105              Can be used as a name resolving function for register_name/3 and
106              re_register_name/3.
107
108              The  function  randomly selects one of the pids for registration
109              and kills the other one.
110
111       random_notify_name(Name, Pid1, Pid2) -> pid()
112
113              Types:
114
115                 Name = term()
116                 Pid1 = Pid2 = pid()
117
118              Can be used as a name resolving function for register_name/3 and
119              re_register_name/3.
120
121              The  function randomly selects one of the pids for registration,
122              and sends the message {global_name_conflict, Name} to the  other
123              pid.
124
125       re_register_name(Name, Pid) -> yes
126
127       re_register_name(Name, Pid, Resolve) -> yes
128
129              Types:
130
131                 Name = term()
132                 Pid = pid()
133                 Resolve = method()
134                 method() =
135                     fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
136                             pid() | none)
137                   {Module, Function} is also allowed.
138
139              Atomically  changes the registered name Name on all nodes to re‐
140              fer to Pid.
141
142              Function Resolve has the same behavior as in register_name/2,3.
143
144       register_name(Name, Pid) -> yes | no
145
146       register_name(Name, Pid, Resolve) -> yes | no
147
148              Types:
149
150                 Name = term()
151                 Pid = pid()
152                 Resolve = method()
153                 method() =
154                     fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
155                             pid() | none)
156                   {Module, Function} is also allowed for backward compatibil‐
157                   ity, but its use is deprecated.
158
159              Globally  associates name Name with a pid, that is, globally no‐
160              tifies all nodes of a new global name in  a  network  of  Erlang
161              nodes.
162
163              When  new  nodes  are added to the network, they are informed of
164              the globally registered names that already exist. The network is
165              also  informed  of any global names in newly connected nodes. If
166              any name clashes are discovered, function Resolve is called. Its
167              purpose  is  to  decide  which  pid  is correct. If the function
168              crashes, or returns anything other than one  of  the  pids,  the
169              name is unregistered. This function is called once for each name
170              clash.
171
172          Warning:
173              If you plan to change code without restarting your  system,  you
174              must use an external fun (fun Module:Function/Arity) as function
175              Resolve. If you use a local fun, you can never replace the  code
176              for the module that the fun belongs to.
177
178
179              Three  predefined  resolve  functions exist: random_exit_name/3,
180              random_notify_name/3, and notify_all_name/3. If no Resolve func‐
181              tion  is  defined, random_exit_name is used. This means that one
182              of the two registered processes is selected as correct while the
183              other is killed.
184
185              This  function  is  completely  synchronous,  that is, when this
186              function returns, the name is either registered on all nodes  or
187              none.
188
189              The  function returns yes if successful, no if it fails. For ex‐
190              ample, no is returned if an attempt is made to register  an  al‐
191              ready  registered  process  or to register a process with a name
192              that is already in use.
193
194          Note:
195              Releases up to and including Erlang/OTP R10 did not check if the
196              process  was  already  registered.  The  global name table could
197              therefore become inconsistent. The old (buggy) behavior  can  be
198              chosen    by    giving    the    Kernel   application   variable
199              global_multi_name_action the value allow.
200
201
202              If a process with a registered name dies, or the node goes down,
203              the name is unregistered on all nodes.
204
205       registered_names() -> [Name]
206
207              Types:
208
209                 Name = term()
210
211              Returns a list of all globally registered names.
212
213       send(Name, Msg) -> Pid
214
215              Types:
216
217                 Name = Msg = term()
218                 Pid = pid()
219
220              Sends message Msg to the pid globally registered as Name.
221
222              If  Name is not a globally registered name, the calling function
223              exits with reason {badarg, {Name, Msg}}.
224
225       set_lock(Id) -> boolean()
226
227       set_lock(Id, Nodes) -> boolean()
228
229       set_lock(Id, Nodes, Retries) -> boolean()
230
231              Types:
232
233                 Id = id()
234                 Nodes = [node()]
235                 Retries = retries()
236                 id() = {ResourceId :: term(), LockRequesterId :: term()}
237                 retries() = integer() >= 0 | infinity
238
239              Sets a lock on the specified nodes (or on all nodes if none  are
240              specified)  on ResourceId for LockRequesterId. If a lock already
241              exists on ResourceId for another requester than LockRequesterId,
242              and  Retries  is  not equal to 0, the process sleeps for a while
243              and tries to execute the action  later.  When  Retries  attempts
244              have been made, false is returned, otherwise true. If Retries is
245              infinity, true is eventually returned (unless the lock is  never
246              released).
247
248              If no value for Retries is specified, infinity is used.
249
250              This function is completely synchronous.
251
252              If  a process that holds a lock dies, or the node goes down, the
253              locks held by the process are deleted.
254
255              The global name server keeps track of all processes sharing  the
256              same  lock,  that  is,  if two processes set the same lock, both
257              processes must delete the lock.
258
259              This function does not address the  problem  of  a  deadlock.  A
260              deadlock  can never occur as long as processes only lock one re‐
261              source at a time. A deadlock can occur if some processes try  to
262              lock  two  or more resources. It is up to the application to de‐
263              tect and rectify a deadlock.
264
265          Note:
266              Avoid the following values of ResourceId,  otherwise  Erlang/OTP
267              does not work properly:
268
269                * dist_ac
270
271                * global
272
273                * mnesia_adjust_log_writes
274
275                * mnesia_table_lock
276
277       sync() -> ok | {error, Reason :: term()}
278
279              Synchronizes the global name server with all nodes known to this
280              node. These are the nodes that are returned from erlang:nodes().
281              When  this  function  returns,  the  global name server receives
282              global information from all nodes. This function can  be  called
283              when new nodes are added to the network.
284
285              The only possible error reason Reason is {"global_groups defini‐
286              tion error", Error}.
287
288       trans(Id, Fun) -> Res | aborted
289
290       trans(Id, Fun, Nodes) -> Res | aborted
291
292       trans(Id, Fun, Nodes, Retries) -> Res | aborted
293
294              Types:
295
296                 Id = id()
297                 Fun = trans_fun()
298                 Nodes = [node()]
299                 Retries = retries()
300                 Res = term()
301                 retries() = integer() >= 0 | infinity
302                 trans_fun() = function() | {module(), atom()}
303
304              Sets a lock on Id (using set_lock/3). If this succeeds, Fun() is
305              evaluated and the result Res is returned. Returns aborted if the
306              lock attempt fails. If Retries is set to infinity, the  transac‐
307              tion does not abort.
308
309              infinity is the default setting and is used if no value is spec‐
310              ified for Retries.
311
312       unregister_name(Name) -> term()
313
314              Types:
315
316                 Name = term()
317
318              Removes the globally registered name Name from  the  network  of
319              Erlang nodes.
320
321       whereis_name(Name) -> pid() | undefined
322
323              Types:
324
325                 Name = term()
326
327              Returns  the pid with the globally registered name Name. Returns
328              undefined if the name is not globally registered.
329

SEE ALSO

331       global_group(3), net_kernel(3)
332
333
334
335Ericsson AB                      kernel 8.1.3                        global(3)
Impressum