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 Warning:
18 By default global does not take any actions to restore a fully con‐
19 nected network when connections are lost due to network issues. This is
20 problematic for all applications expecting a fully connected network to
21 be provided, such as for example mnesia, but also for global itself. A
22 network of overlapping partitions might cause the internal state of
23 global to become inconsistent. Such an inconsistency can remain even
24 after such partitions have been brought together to form a fully con‐
25 nected network again. The effect on other applications that expects
26 that a fully connected network is maintained may vary, but they might
27 misbehave in very subtle hard to detect ways during such a partition‐
28 ing.
29 In order to prevent such issues, we have introduced a prevent overlap‐
31 ping partitions fix which can be enabled using the prevent_overlap‐
32 ping_partitions kernel(6) parameter. When this fix has been enabled,
33 global will actively disconnect from nodes that reports that they have
34 lost connections to other nodes. This will cause fully connected parti‐
35 tions to form instead of leaving the network in a state with overlap‐
36 ping partitions. Note that this fix has to be enabled on all nodes in
37 the network in order to work properly. Since this quite substantially
38 changes the behavior, this fix is currently disabled by default. Since
39 you might get hard to detect issues without this fix you are, however,
40 strongly advised to enable this fix in order to avoid issues such as
41 the ones described above. As of OTP 25 this fix will become enabled by
42 default.
43 These services are controlled through the process global_name_server
46 that exists on every node. The global name server starts automatically
47 when a node is started. With the term global is meant over a system
48 consisting of many Erlang nodes.
49 The ability to globally register names is a central concept in the pro‐
51 gramming of distributed Erlang systems. In this module, the equivalent
52 of the register/2 and whereis/1 BIFs (for local name registration) are
53 provided, but for a network of Erlang nodes. A registered name is an
54 alias for a process identifier (pid). The global name server monitors
55 globally registered pids. If a process terminates, the name is also
56 globally unregistered.
57 The registered names are stored in replica global name tables on every
59 node. There is no central storage point. Thus, the translation of a
60 name to a pid is fast, as it is always done locally. For any action re‐
61 sulting in a change to the global name table, all tables on other nodes
62 are automatically updated.
63 Global locks have lock identities and are set on a specific resource.
65 For example, the specified resource can be a pid. When a global lock is
66 set, access to the locked resource is denied for all resources other
67 than the lock requester.
68 Both the registration and lock services are atomic. All nodes involved
70 in these actions have the same view of the information.
71 The global name server also performs the critical task of continuously
73 monitoring changes in node configuration. If a node that runs a glob‐
74 ally registered process goes down, the name is globally unregistered.
75 To this end, the global name server subscribes to nodeup and nodedown
76 messages sent from module net_kernel. Relevant Kernel application vari‐
77 ables in this context are net_setuptime, net_ticktime, and
78 dist_auto_connect. See also kernel(6).
79 The name server also maintains a fully connected network. For example,
81 if node N1 connects to node N2 (which is already connected to N3), the
82 global name servers on the nodes N1 and N3 ensure that also N1 and N3
83 are connected. If this is not desired, command-line flag -connect_all
84 false can be used (see also erl(1)). In this case, the name registra‐
85 tion service cannot be used, but the lock mechanism still works.
86 If the global name server fails to connect nodes (N1 and N3 in the ex‐
88 ample), a warning event is sent to the error logger. The presence of
89 such an event does not exclude the nodes to connect later (you can, for
90 example, try command rpc:call(N1, net_adm, ping, [N2]) in the Erlang
91 shell), but it indicates a network problem.
92 Note:
94 If the fully connected network is not set up properly, try first to in‐
95 crease the value of net_setuptime.
96
99 id() = {ResourceId :: term(), LockRequesterId :: term()}
100
102 del_lock(Id) -> true
103 del_lock(Id, Nodes) -> true
105 Types:
107 Id = id()
109 Nodes = [node()]
110 Deletes the lock Id synchronously.
112 notify_all_name(Name, Pid1, Pid2) -> none
114 Types:
116 Name = term()
118 Pid1 = Pid2 = pid()
119 Can be used as a name resolving function for register_name/3 and
121 re_register_name/3.
122 The function unregisters both pids and sends the message
124 {global_name_conflict, Name, OtherPid} to both processes.
125 random_exit_name(Name, Pid1, Pid2) -> pid()
127 Types:
129 Name = term()
131 Pid1 = Pid2 = pid()
132 Can be used as a name resolving function for register_name/3 and
134 re_register_name/3.
135 The function randomly selects one of the pids for registration
137 and kills the other one.
138 random_notify_name(Name, Pid1, Pid2) -> pid()
140 Types:
142 Name = term()
144 Pid1 = Pid2 = pid()
145 Can be used as a name resolving function for register_name/3 and
147 re_register_name/3.
148 The function randomly selects one of the pids for registration,
150 and sends the message {global_name_conflict, Name} to the other
151 pid.
152 re_register_name(Name, Pid) -> yes
154 re_register_name(Name, Pid, Resolve) -> yes
156 Types:
158 Name = term()
160 Pid = pid()
161 Resolve = method()
162 method() =
163 fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
164 pid() | none)
165 {Module, Function} is also allowed.
166 Atomically changes the registered name Name on all nodes to re‐
168 fer to Pid.
169 Function Resolve has the same behavior as in register_name/2,3.
171 register_name(Name, Pid) -> yes | no
173 register_name(Name, Pid, Resolve) -> yes | no
175 Types:
177 Name = term()
179 Pid = pid()
180 Resolve = method()
181 method() =
182 fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
183 pid() | none)
184 {Module, Function} is also allowed for backward compatibil‐
185 ity, but its use is deprecated.
186 Globally associates name Name with a pid, that is, globally no‐
188 tifies all nodes of a new global name in a network of Erlang
189 nodes.
190 When new nodes are added to the network, they are informed of
192 the globally registered names that already exist. The network is
193 also informed of any global names in newly connected nodes. If
194 any name clashes are discovered, function Resolve is called. Its
195 purpose is to decide which pid is correct. If the function
196 crashes, or returns anything other than one of the pids, the
197 name is unregistered. This function is called once for each name
198 clash.
199 Warning:
201 If you plan to change code without restarting your system, you
202 must use an external fun (fun Module:Function/Arity) as function
203 Resolve. If you use a local fun, you can never replace the code
204 for the module that the fun belongs to.
205 Three predefined resolve functions exist: random_exit_name/3,
208 random_notify_name/3, and notify_all_name/3. If no Resolve func‐
209 tion is defined, random_exit_name is used. This means that one
210 of the two registered processes is selected as correct while the
211 other is killed.
212 This function is completely synchronous, that is, when this
214 function returns, the name is either registered on all nodes or
215 none.
216 The function returns yes if successful, no if it fails. For ex‐
218 ample, no is returned if an attempt is made to register an al‐
219 ready registered process or to register a process with a name
220 that is already in use.
221 Note:
223 Releases up to and including Erlang/OTP R10 did not check if the
224 process was already registered. The global name table could
225 therefore become inconsistent. The old (buggy) behavior can be
226 chosen by giving the Kernel application variable
227 global_multi_name_action the value allow.
228 If a process with a registered name dies, or the node goes down,
231 the name is unregistered on all nodes.
232 registered_names() -> [Name]
234 Types:
236 Name = term()
238 Returns a list of all globally registered names.
240 send(Name, Msg) -> Pid
242 Types:
244 Name = Msg = term()
246 Pid = pid()
247 Sends message Msg to the pid globally registered as Name.
249 If Name is not a globally registered name, the calling function
251 exits with reason {badarg, {Name, Msg}}.
252 set_lock(Id) -> boolean()
254 set_lock(Id, Nodes) -> boolean()
256 set_lock(Id, Nodes, Retries) -> boolean()
258 Types:
260 Id = id()
262 Nodes = [node()]
263 Retries = retries()
264 id() = {ResourceId :: term(), LockRequesterId :: term()}
265 retries() = integer() >= 0 | infinity
266 Sets a lock on the specified nodes (or on all nodes if none are
268 specified) on ResourceId for LockRequesterId. If a lock already
269 exists on ResourceId for another requester than LockRequesterId,
270 and Retries is not equal to 0, the process sleeps for a while
271 and tries to execute the action later. When Retries attempts
272 have been made, false is returned, otherwise true. If Retries is
273 infinity, true is eventually returned (unless the lock is never
274 released).
275 If no value for Retries is specified, infinity is used.
277 This function is completely synchronous.
279 If a process that holds a lock dies, or the node goes down, the
281 locks held by the process are deleted.
282 The global name server keeps track of all processes sharing the
284 same lock, that is, if two processes set the same lock, both
285 processes must delete the lock.
286 This function does not address the problem of a deadlock. A
288 deadlock can never occur as long as processes only lock one re‐
289 source at a time. A deadlock can occur if some processes try to
290 lock two or more resources. It is up to the application to de‐
291 tect and rectify a deadlock.
292 Note:
294 Avoid the following values of ResourceId, otherwise Erlang/OTP
295 does not work properly:
296 * dist_ac
298 * global
300 * mnesia_adjust_log_writes
302 * mnesia_table_lock
304 sync() -> ok | {error, Reason :: term()}
306 Synchronizes the global name server with all nodes known to this
308 node. These are the nodes that are returned from erlang:nodes().
309 When this function returns, the global name server receives
310 global information from all nodes. This function can be called
311 when new nodes are added to the network.
312 The only possible error reason Reason is {"global_groups defini‐
314 tion error", Error}.
315 trans(Id, Fun) -> Res | aborted
317 trans(Id, Fun, Nodes) -> Res | aborted
319 trans(Id, Fun, Nodes, Retries) -> Res | aborted
321 Types:
323 Id = id()
325 Fun = trans_fun()
326 Nodes = [node()]
327 Retries = retries()
328 Res = term()
329 retries() = integer() >= 0 | infinity
330 trans_fun() = function() | {module(), atom()}
331 Sets a lock on Id (using set_lock/3). If this succeeds, Fun() is
333 evaluated and the result Res is returned. Returns aborted if the
334 lock attempt fails. If Retries is set to infinity, the transac‐
335 tion does not abort.
336 infinity is the default setting and is used if no value is spec‐
338 ified for Retries.
339 unregister_name(Name) -> term()
341 Types:
343 Name = term()
345 Removes the globally registered name Name from the network of
347 Erlang nodes.
348 whereis_name(Name) -> pid() | undefined
350 Types:
352 Name = term()
354 Returns the pid with the globally registered name Name. Returns
356 undefined if the name is not globally registered.
357
359 global_group(3), net_kernel(3)
360Ericsson AB kernel 8.3.2 global(3)