.TH global 3erl "kernel 5.1.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
global \- A global name registration facility.
.SH DESCRIPTION
.LP
This module consists of the following services:
.RS 2
.TP 2
*
Registration of global names
.LP
.TP 2
*
Global locks
.LP
.TP 2
*
Maintenance of the fully connected network
.LP
.RE

.LP
These services are controlled through the process \fIglobal_name_server\fR\& that exists on every node\&. The global name server starts automatically when a node is started\&. With the term \fIglobal\fR\& is meant over a system consisting of many Erlang nodes\&.
.LP
The ability to globally register names is a central concept in the programming of distributed Erlang systems\&. In this module, the equivalent of the \fIregister/2\fR\& and \fIwhereis/1\fR\& BIFs (for local name registration) are provided, but for a network of Erlang nodes\&. A registered name is an alias for a process identifier (pid)\&. The global name server monitors globally registered pids\&. If a process terminates, the name is also globally unregistered\&.
.LP
The registered names are stored in replica global name tables on every node\&. There is no central storage point\&. Thus, the translation of a name to a pid is fast, as it is always done locally\&. For any action resulting in a change to the global name table, all tables on other nodes are automatically updated\&.
.LP
Global locks have lock identities and are set on a specific resource\&. For example, the specified resource can be a pid\&. When a global lock is set, access to the locked resource is denied for all resources other than the lock requester\&.
.LP
Both the registration and lock services are atomic\&. All nodes involved in these actions have the same view of the information\&.
.LP
The global name server also performs the critical task of continuously monitoring changes in node configuration\&. If a node that runs a globally registered process goes down, the name is globally unregistered\&. To this end, the global name server subscribes to \fInodeup\fR\& and \fInodedown\fR\& messages sent from module \fInet_kernel\fR\&\&. Relevant Kernel application variables in this context are \fInet_setuptime\fR\&, \fInet_ticktime\fR\&, and \fIdist_auto_connect\fR\&\&. See also \fB\fIkernel(7)\fR\&\fR\&\&.
.LP
The name server also maintains a fully connected network\&. For example, if node \fIN1\fR\& connects to node \fIN2\fR\& (which is already connected to \fIN3\fR\&), the global name servers on the nodes \fIN1\fR\& and \fIN3\fR\& ensure that also \fIN1\fR\& and \fIN3\fR\& are connected\&. If this is not desired, command-line flag \fI-connect_all false\fR\& can be used (see also \fB\fIerl(1)\fR\&\fR\&)\&. In this case, the name registration service cannot be used, but the lock mechanism still works\&.
.LP
If the global name server fails to connect nodes (\fIN1\fR\& and \fIN3\fR\& in the example), a warning event is sent to the error logger\&. The presence of such an event does not exclude the nodes to connect later (you can, for example, try command \fIrpc:call(N1, net_adm, ping, [N2])\fR\& in the Erlang shell), but it indicates a network problem\&.
.LP

.RS -4
.B
Note:
.RE
If the fully connected network is not set up properly, try first to increase the value of \fInet_setuptime\fR\&\&.

.SH DATA TYPES
.nf

\fBid()\fR\& = {ResourceId :: term(), LockRequesterId :: term()}
.br
.fi
.SH EXPORTS
.LP
.nf

.B
del_lock(Id) -> true
.br
.fi
.br
.nf

.B
del_lock(Id, Nodes) -> true
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Id = \fBid()\fR\&
.br
Nodes = [node()]
.br
.RE
.RE
.RS
.LP
Deletes the lock \fIId\fR\& synchronously\&.
.RE

.LP
.nf

.B
notify_all_name(Name, Pid1, Pid2) -> none
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
Pid1 = Pid2 = pid()
.br
.RE
.RE
.RS
.LP
Can be used as a name resolving function for \fB\fIregister_name/3\fR\&\fR\& and \fB\fIre_register_name/3\fR\&\fR\&\&.
.LP
The function unregisters both pids and sends the message \fI{global_name_conflict, Name, OtherPid}\fR\& to both processes\&.
.RE

.LP
.nf

.B
random_exit_name(Name, Pid1, Pid2) -> pid()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
Pid1 = Pid2 = pid()
.br
.RE
.RE
.RS
.LP
Can be used as a name resolving function for \fB\fIregister_name/3\fR\&\fR\& and \fB\fIre_register_name/3\fR\&\fR\&\&.
.LP
The function randomly selects one of the pids for registration and kills the other one\&.
.RE

.LP
.nf

.B
random_notify_name(Name, Pid1, Pid2) -> pid()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
Pid1 = Pid2 = pid()
.br
.RE
.RE
.RS
.LP
Can be used as a name resolving function for \fB\fIregister_name/3\fR\&\fR\& and \fB\fIre_register_name/3\fR\&\fR\&\&.
.LP
The function randomly selects one of the pids for registration, and sends the message \fI{global_name_conflict, Name}\fR\& to the other pid\&.
.RE

.LP
.nf

.B
re_register_name(Name, Pid) -> yes
.br
.fi
.br
.nf

.B
re_register_name(Name, Pid, Resolve) -> yes
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
Pid = pid()
.br
Resolve = \fBmethod()\fR\&
.br
.nf
\fBmethod()\fR\& = 
.br
    fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
.br
            pid() | none)
.fi
.br
.RS 2
{\fIModule\fR\&, \fIFunction\fR\&} is also allowed\&. 
.RE
.RE
.RE
.RS
.LP
Atomically changes the registered name \fIName\fR\& on all nodes to refer to \fIPid\fR\&\&.
.LP
Function \fIResolve\fR\& has the same behavior as in \fB\fIregister_name/2,3\fR\&\fR\&\&.
.RE

.LP
.nf

.B
register_name(Name, Pid) -> yes | no
.br
.fi
.br
.nf

.B
register_name(Name, Pid, Resolve) -> yes | no
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
Pid = pid()
.br
Resolve = \fBmethod()\fR\&
.br
.nf
\fBmethod()\fR\& = 
.br
    fun((Name :: term(), Pid :: pid(), Pid2 :: pid()) ->
.br
            pid() | none)
.fi
.br
.RS 2
{\fIModule\fR\&, \fIFunction\fR\&} is also allowed for backward compatibility, but its use is deprecated\&. 
.RE
.RE
.RE
.RS
.LP
Globally associates name \fIName\fR\& with a pid, that is, globally notifies all nodes of a new global name in a network of Erlang nodes\&.
.LP
When new nodes are added to the network, they are informed of the globally registered names that already exist\&. The network is also informed of any global names in newly connected nodes\&. If any name clashes are discovered, function \fIResolve\fR\& is called\&. Its purpose is to decide which pid is correct\&. If the function crashes, or returns anything other than one of the pids, the name is unregistered\&. This function is called once for each name clash\&.
.LP

.RS -4
.B
Warning:
.RE
If you plan to change code without restarting your system, you must use an external fun (\fIfun Module:Function/Arity\fR\&) as function \fIResolve\fR\&\&. If you use a local fun, you can never replace the code for the module that the fun belongs to\&.

.LP
Three predefined resolve functions exist: \fIrandom_exit_name/3\fR\&, \fIrandom_notify_name/3\fR\&, and \fInotify_all_name/3\fR\&\&. If no \fIResolve\fR\& function is defined, \fIrandom_exit_name\fR\& is used\&. This means that one of the two registered processes is selected as correct while the other is killed\&.
.LP
This function is completely synchronous, that is, when this function returns, the name is either registered on all nodes or none\&.
.LP
The function returns \fIyes\fR\& if successful, \fIno\fR\& if it fails\&. For example, \fIno\fR\& is returned if an attempt is made to register an already registered process or to register a process with a name that is already in use\&.
.LP

.RS -4
.B
Note:
.RE
Releases up to and including Erlang/OTP R10 did not check if the process was already registered\&. The global name table could therefore become inconsistent\&. The old (buggy) behavior can be chosen by giving the Kernel application variable \fIglobal_multi_name_action\fR\& the value \fIallow\fR\&\&.

.LP
If a process with a registered name dies, or the node goes down, the name is unregistered on all nodes\&.
.RE

.LP
.nf

.B
registered_names() -> [Name]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
.RE
.RE
.RS
.LP
Returns a list of all globally registered names\&.
.RE

.LP
.nf

.B
send(Name, Msg) -> Pid
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = Msg = term()
.br
Pid = pid()
.br
.RE
.RE
.RS
.LP
Sends message \fIMsg\fR\& to the pid globally registered as \fIName\fR\&\&.
.LP
If \fIName\fR\& is not a globally registered name, the calling function exits with reason \fI{badarg, {Name, Msg}}\fR\&\&.
.RE

.LP
.nf

.B
set_lock(Id) -> boolean()
.br
.fi
.br
.nf

.B
set_lock(Id, Nodes) -> boolean()
.br
.fi
.br
.nf

.B
set_lock(Id, Nodes, Retries) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Id = \fBid()\fR\&
.br
Nodes = [node()]
.br
Retries = \fBretries()\fR\&
.br
.nf
\fBid()\fR\& = {ResourceId :: term(), LockRequesterId :: term()}
.fi
.br
.nf
\fBretries()\fR\& = integer() >= 0 | infinity
.fi
.br
.RE
.RE
.RS
.LP
Sets a lock on the specified nodes (or on all nodes if none are specified) on \fIResourceId\fR\& for \fILockRequesterId\fR\&\&. If a lock already exists on \fIResourceId\fR\& for another requester than \fILockRequesterId\fR\&, and \fIRetries\fR\& is not equal to \fI0\fR\&, the process sleeps for a while and tries to execute the action later\&. When \fIRetries\fR\& attempts have been made, \fIfalse\fR\& is returned, otherwise \fItrue\fR\&\&. If \fIRetries\fR\& is \fIinfinity\fR\&, \fItrue\fR\& is eventually returned (unless the lock is never released)\&.
.LP
If no value for \fIRetries\fR\& is specified, \fIinfinity\fR\& is used\&.
.LP
This function is completely synchronous\&.
.LP
If a process that holds a lock dies, or the node goes down, the locks held by the process are deleted\&.
.LP
The global name server keeps track of all processes sharing the same lock, that is, if two processes set the same lock, both processes must delete the lock\&.
.LP
This function does not address the problem of a deadlock\&. A deadlock can never occur as long as processes only lock one resource at a time\&. A deadlock can occur if some processes try to lock two or more resources\&. It is up to the application to detect and rectify a deadlock\&.
.LP

.RS -4
.B
Note:
.RE
Avoid the following values of \fIResourceId\fR\&, otherwise Erlang/OTP does not work properly:
.RS 2
.TP 2
*
\fIdist_ac\fR\&
.LP
.TP 2
*
\fIglobal\fR\&
.LP
.TP 2
*
\fImnesia_adjust_log_writes\fR\&
.LP
.TP 2
*
\fImnesia_table_lock\fR\&
.LP
.TP 2
*
\fIpg2\fR\&
.LP
.RE


.RE

.LP
.nf

.B
sync() -> ok | {error, Reason :: term()}
.br
.fi
.br
.RS
.LP
Synchronizes the global name server with all nodes known to this node\&. These are the nodes that are returned from \fIerlang:nodes()\fR\&\&. When this function returns, the global name server receives global information from all nodes\&. This function can be called when new nodes are added to the network\&.
.LP
The only possible error reason \fIReason\fR\& is \fI{"global_groups definition error", Error}\fR\&\&.
.RE

.LP
.nf

.B
trans(Id, Fun) -> Res | aborted
.br
.fi
.br
.nf

.B
trans(Id, Fun, Nodes) -> Res | aborted
.br
.fi
.br
.nf

.B
trans(Id, Fun, Nodes, Retries) -> Res | aborted
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Id = \fBid()\fR\&
.br
Fun = \fBtrans_fun()\fR\&
.br
Nodes = [node()]
.br
Retries = \fBretries()\fR\&
.br
Res = term()
.br
.nf
\fBretries()\fR\& = integer() >= 0 | infinity
.fi
.br
.nf
\fBtrans_fun()\fR\& = function() | {module(), atom()}
.fi
.br
.RE
.RE
.RS
.LP
Sets a lock on \fIId\fR\& (using \fB\fIset_lock/3\fR\&\fR\&)\&. If this succeeds, \fIFun()\fR\& is evaluated and the result \fIRes\fR\& is returned\&. Returns \fIaborted\fR\& if the lock attempt fails\&. If \fIRetries\fR\& is set to \fIinfinity\fR\&, the transaction does not abort\&.
.LP
\fIinfinity\fR\& is the default setting and is used if no value is specified for \fIRetries\fR\&\&.
.RE

.LP
.nf

.B
unregister_name(Name) -> term()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
.RE
.RE
.RS
.LP
Removes the globally registered name \fIName\fR\& from the network of Erlang nodes\&.
.RE

.LP
.nf

.B
whereis_name(Name) -> pid() | undefined
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = term()
.br
.RE
.RE
.RS
.LP
Returns the pid with the globally registered name \fIName\fR\&\&. Returns \fIundefined\fR\& if the name is not globally registered\&.
.RE

.SH "SEE ALSO"

.LP
\fB\fIglobal_group(3erl)\fR\&\fR\&, \fB\fInet_kernel(3erl)\fR\&\fR\&