1global(3) Erlang Module Definition global(3)
2
6 global - A global name registration facility.
7
9 This module consists of the following services:
10 * Registration of global names
12 * Global locks
14 * Maintenance of the fully connected network
16 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 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 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 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 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 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 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 Both the registration and lock services are atomic. All nodes involved
73 in these actions have the same view of the information.
74 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 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 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 Note:
96 If the fully connected network is not set up properly, try first to in‐
97 crease the value of net_setuptime.
98
101 id() = {ResourceId :: term(), LockRequesterId :: term()}
102
104 del_lock(Id) -> true
105 del_lock(Id, Nodes) -> true
107 Types:
109 Id = id()
111 Nodes = [node()]
112 Deletes the lock Id synchronously.
114 disconnect() -> [node()]
116 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 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 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 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 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 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 notify_all_name(Name, Pid1, Pid2) -> none
161 Types:
163 Name = term()
165 Pid1 = Pid2 = pid()
166 Can be used as a name resolving function for register_name/3 and
168 re_register_name/3.
169 The function unregisters both pids and sends the message
171 {global_name_conflict, Name, OtherPid} to both processes.
172 random_exit_name(Name, Pid1, Pid2) -> pid()
174 Types:
176 Name = term()
178 Pid1 = Pid2 = pid()
179 Can be used as a name resolving function for register_name/3 and
181 re_register_name/3.
182 The function randomly selects one of the pids for registration
184 and kills the other one.
185 random_notify_name(Name, Pid1, Pid2) -> pid()
187 Types:
189 Name = term()
191 Pid1 = Pid2 = pid()
192 Can be used as a name resolving function for register_name/3 and
194 re_register_name/3.
195 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 re_register_name(Name, Pid) -> yes
201 re_register_name(Name, Pid, Resolve) -> yes
203 Types:
205 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 Atomically changes the registered name Name on all nodes to re‐
215 fer to Pid.
216 Function Resolve has the same behavior as in register_name/2,3.
218 register_name(Name, Pid) -> yes | no
220 register_name(Name, Pid, Resolve) -> yes | no
222 Types:
224 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 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 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 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 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 This function is completely synchronous, that is, when this
261 function returns, the name is either registered on all nodes or
262 none.
263 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 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 If a process with a registered name dies, or the node goes down,
278 the name is unregistered on all nodes.
279 registered_names() -> [Name]
281 Types:
283 Name = term()
285 Returns a list of all globally registered names.
287 send(Name, Msg) -> Pid
289 Types:
291 Name = Msg = term()
293 Pid = pid()
294 Sends message Msg to the pid globally registered as Name.
296 If Name is not a globally registered name, the calling function
298 exits with reason {badarg, {Name, Msg}}.
299 set_lock(Id) -> boolean()
301 set_lock(Id, Nodes) -> boolean()
303 set_lock(Id, Nodes, Retries) -> boolean()
305 Types:
307 Id = id()
309 Nodes = [node()]
310 Retries = retries()
311 id() = {ResourceId :: term(), LockRequesterId :: term()}
312 retries() = integer() >= 0 | infinity
313 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 If no value for Retries is specified, infinity is used.
324 This function is completely synchronous.
326 If a process that holds a lock dies, or the node goes down, the
328 locks held by the process are deleted.
329 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 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 Note:
341 Avoid the following values of ResourceId, otherwise Erlang/OTP
342 does not work properly:
343 * dist_ac
345 * global
347 * mnesia_adjust_log_writes
349 * mnesia_table_lock
351 sync() -> ok | {error, Reason :: term()}
353 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 The only possible error reason Reason is {"global_groups defini‐
361 tion error", Error}.
362 trans(Id, Fun) -> Res | aborted
364 trans(Id, Fun, Nodes) -> Res | aborted
366 trans(Id, Fun, Nodes, Retries) -> Res | aborted
368 Types:
370 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 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 infinity is the default setting and is used if no value is spec‐
385 ified for Retries.
386 unregister_name(Name) -> term()
388 Types:
390 Name = term()
392 Removes the globally registered name Name from the network of
394 Erlang nodes.
395 whereis_name(Name) -> pid() | undefined
397 Types:
399 Name = term()
401 Returns the pid with the globally registered name Name. Returns
403 undefined if the name is not globally registered.
404
406 global_group(3), net_kernel(3)
407Ericsson AB kernel 8.5.3 global(3)