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 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 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 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
33 resulting in a change to the global name table, all tables on other
34 nodes are automatically updated.
35 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 Both the registration and lock services are atomic. All nodes involved
42 in these actions have the same view of the information.
43 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 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 If the global name server fails to connect nodes (N1 and N3 in the
60 example), 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 Note:
66 If the fully connected network is not set up properly, try first to
67 increase the value of net_setuptime.
68
71 id() = {ResourceId :: term(), LockRequesterId :: term()}
72
74 del_lock(Id) -> true
75 del_lock(Id, Nodes) -> true
77 Types:
79 Id = id()
81 Nodes = [node()]
82 Deletes the lock Id synchronously.
84 notify_all_name(Name, Pid1, Pid2) -> none
86 Types:
88 Name = term()
90 Pid1 = Pid2 = pid()
91 Can be used as a name resolving function for register_name/3 and
93 re_register_name/3.
94 The function unregisters both pids and sends the message
96 {global_name_conflict, Name, OtherPid} to both processes.
97 random_exit_name(Name, Pid1, Pid2) -> pid()
99 Types:
101 Name = term()
103 Pid1 = Pid2 = pid()
104 Can be used as a name resolving function for register_name/3 and
106 re_register_name/3.
107 The function randomly selects one of the pids for registration
109 and kills the other one.
110 random_notify_name(Name, Pid1, Pid2) -> pid()
112 Types:
114 Name = term()
116 Pid1 = Pid2 = pid()
117 Can be used as a name resolving function for register_name/3 and
119 re_register_name/3.
120 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 re_register_name(Name, Pid) -> yes
126 re_register_name(Name, Pid, Resolve) -> yes
128 Types:
130 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 Atomically changes the registered name Name on all nodes to
140 refer to Pid.
141 Function Resolve has the same behavior as in register_name/2,3.
143 register_name(Name, Pid) -> yes | no
145 register_name(Name, Pid, Resolve) -> yes | no
147 Types:
149 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 Globally associates name Name with a pid, that is, globally
160 notifies all nodes of a new global name in a network of Erlang
161 nodes.
162 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 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 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 This function is completely synchronous, that is, when this
186 function returns, the name is either registered on all nodes or
187 none.
188 The function returns yes if successful, no if it fails. For
190 example, no is returned if an attempt is made to register an
191 already registered process or to register a process with a name
192 that is already in use.
193 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 If a process with a registered name dies, or the node goes down,
203 the name is unregistered on all nodes.
204 registered_names() -> [Name]
206 Types:
208 Name = term()
210 Returns a list of all globally registered names.
212 send(Name, Msg) -> Pid
214 Types:
216 Name = Msg = term()
218 Pid = pid()
219 Sends message Msg to the pid globally registered as Name.
221 If Name is not a globally registered name, the calling function
223 exits with reason {badarg, {Name, Msg}}.
224 set_lock(Id) -> boolean()
226 set_lock(Id, Nodes) -> boolean()
228 set_lock(Id, Nodes, Retries) -> boolean()
230 Types:
232 Id = id()
234 Nodes = [node()]
235 Retries = retries()
236 id() = {ResourceId :: term(), LockRequesterId :: term()}
237 retries() = integer() >= 0 | infinity
238 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 If no value for Retries is specified, infinity is used.
249 This function is completely synchronous.
251 If a process that holds a lock dies, or the node goes down, the
253 locks held by the process are deleted.
254 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 This function does not address the problem of a deadlock. A
260 deadlock can never occur as long as processes only lock one
261 resource at a time. A deadlock can occur if some processes try
262 to lock two or more resources. It is up to the application to
263 detect and rectify a deadlock.
264 Note:
266 Avoid the following values of ResourceId, otherwise Erlang/OTP
267 does not work properly:
268 * dist_ac
270 * global
272 * mnesia_adjust_log_writes
274 * mnesia_table_lock
276 * pg2
278 sync() -> ok | {error, Reason :: term()}
280 Synchronizes the global name server with all nodes known to this
282 node. These are the nodes that are returned from erlang:nodes().
283 When this function returns, the global name server receives
284 global information from all nodes. This function can be called
285 when new nodes are added to the network.
286 The only possible error reason Reason is {"global_groups defini‐
288 tion error", Error}.
289 trans(Id, Fun) -> Res | aborted
291 trans(Id, Fun, Nodes) -> Res | aborted
293 trans(Id, Fun, Nodes, Retries) -> Res | aborted
295 Types:
297 Id = id()
299 Fun = trans_fun()
300 Nodes = [node()]
301 Retries = retries()
302 Res = term()
303 retries() = integer() >= 0 | infinity
304 trans_fun() = function() | {module(), atom()}
305 Sets a lock on Id (using set_lock/3). If this succeeds, Fun() is
307 evaluated and the result Res is returned. Returns aborted if the
308 lock attempt fails. If Retries is set to infinity, the transac‐
309 tion does not abort.
310 infinity is the default setting and is used if no value is spec‐
312 ified for Retries.
313 unregister_name(Name) -> term()
315 Types:
317 Name = term()
319 Removes the globally registered name Name from the network of
321 Erlang nodes.
322 whereis_name(Name) -> pid() | undefined
324 Types:
326 Name = term()
328 Returns the pid with the globally registered name Name. Returns
330 undefined if the name is not globally registered.
331
333 global_group(3), net_kernel(3)
334Ericsson AB kernel 7.3 global(3)