Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
global(3)		   Erlang Module Definition		     global(3)

       global -	A Global Name Registration Facility

       This  documentation  describes  the Global module which consists	of the
       following functionalities:

	 * registration	of global names;

	 * global locks;

	 * maintenance of the fully connected network.

       These services are controlled via the process global_name_server	 which
       exists  on  every node. The global name server is started automatically
       when a node is started. With the	term global is	meant  over  a	system
       consisting of several Erlang nodes.

       The ability to globally register	names is a central concept in the pro-
       gramming	of distributed Erlang systems. In this module, the  equivalent
       of  the register/2 and whereis/1	BIFs (for local	name registration) are
       implemented, 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  will  also
       be globally unregistered.

       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. When any action in
       taken which results in a	change to the global name table, all tables on
       other nodes are automatically updated.

       Global  locks  have lock	identities and are set on a specific resource.
       For instance, the specified resource could be a pid. When a global lock
       is set, access to the locked resource is	denied for all other resources
       other than the lock requester.

       Both the	registration and lock functionalities are  atomic.  All	 nodes
       involved	in these actions will have the same view of the	information.

       The  global name	server also performs the critical task of continuously
       monitoring changes in node configuration: if a node which runs a	 glob-
       ally  registered	 process goes down, the	name will be globally unregis-
       tered. To this end the global name  server  subscribes  to  nodeup  and
       nodedown	 messages sent from the	net_kernel module. Relevant Kernel ap-
       plication variables in this context  are	 net_setuptime,	 net_ticktime,
       and dist_auto_connect. See also kernel(6).

       The name	server will also maintain a fully connected network. For exam-
       ple, if node N1 connects	to node	N2 (which is already connected to N3),
       the global name servers on the nodes N1 and N3 will make	sure that also
       N1 and N3 are connected.	If this	is not desired,	the command line  flag
       -connect_all false can be used (see also	erl(1)). In this case the name
       registration facility cannot be used, but the lock mechanism will still

       If  the global name server fails	to connect nodes (N1 and N3 in the ex-
       ample above) a warning event is sent to the error logger. The  presence
       of  such	 an event does not exclude the possibility that	the nodes will
       later  connect--one  can	 for  example  try  the	 command  rpc:call(N1,
       net_adm,	ping, [N2]) in the Erlang shell--but it	indicates some kind of
       problem with the	network.

       If the fully connected network is not set up properly, the first	 thing
       to try is to increase the value of net_setuptime.

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

       del_lock(Id) -> true

       del_lock(Id, Nodes) -> true


		 Id = id()
		 Nodes = [node()]

	      Deletes the lock Id synchronously.

       notify_all_name(Name, Pid1, Pid2) -> none


		 Name =	term()
		 Pid1 =	Pid2 = pid()

	      This  function can be used as a name resolving function for reg-
	      ister_name/3 and re_register_name/3. It unregisters  both	 pids,
	      and  sends the message {global_name_conflict, Name, OtherPid} to
	      both processes.

       random_exit_name(Name, Pid1, Pid2) -> pid()


		 Name =	term()
		 Pid1 =	Pid2 = pid()

	      This function can	be used	as a name resolving function for  reg-
	      ister_name/3  and	re_register_name/3. It randomly	chooses	one of
	      the pids for registration	and kills the other one.

       random_notify_name(Name,	Pid1, Pid2) -> pid()


		 Name =	term()
		 Pid1 =	Pid2 = pid()

	      This function can	be used	as a name resolving function for  reg-
	      ister_name/3  and	re_register_name/3. It randomly	chooses	one of
	      the   pids   for	 registration,	 and   sends	the    message
	      {global_name_conflict, Name} to the other	pid.

       register_name(Name, Pid)	-> yes | no

       register_name(Name, Pid,	Resolve) -> yes	| no


		 Name =	term()
		 Pid = pid()
		 Resolve = method()
		 method() =
		     fun((Name :: term(), Pid :: pid(),	Pid2 ::	pid()) ->
			     pid() | none)
		   {Module,  Function}	is currently also allowed for backward
		   compatibility, but its use is deprecated

	      Globally associates the name Name	with a pid, that is,  Globally
	      notifies	all  nodes of a	new global name	in a network of	Erlang

	      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, the Resolve function 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

	      If  you  plan to change code without restarting your system, you
	      must use an external fun (fun Module:Function/Arity) as the  Re-
	      solve function; if you use a local fun you can never replace the
	      code for the module that the fun belongs to.

	      There   are   three   pre-defined	  resolve   functions:	  ran-
	      dom_exit_name/3, random_notify_name/3, and notify_all_name/3. If
	      no Resolve function is defined, random_exit_name is  used.  This
	      means  that one of the two registered processes will be selected
	      as correct while the other is killed.

	      This function is completely synchronous. This  means  that  when
	      this  function  returns,	the  name  is either registered	on all
	      nodes or none.

	      The function returns yes if successful, no if it fails. For  ex-
	      ample,  no  is returned if an attempt is made to register	an al-
	      ready registered process or to register a	process	 with  a  name
	      that is already in use.

	      Releases	up  to	and  including	OTP  R10  did not check	if the
	      process was already registered. As a consequence the global name
	      table could become inconsistent. The old (buggy) behavior	can be
	      chosen   by   giving    the    Kernel    application    variable
	      global_multi_name_action the value allow.

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

       registered_names() -> [Name]


		 Name =	term()

	      Returns a	lists of all globally registered names.

       re_register_name(Name, Pid) -> yes

       re_register_name(Name, Pid, Resolve) -> yes


		 Name =	term()
		 Pid = pid()
		 Resolve = method()
		 method() =
		     fun((Name :: term(), Pid :: pid(),	Pid2 ::	pid()) ->
			     pid() | none)
		   {Module, Function} is also allowed

	      Atomically changes the registered	name Name on all nodes to  re-
	      fer to Pid.

	      The  Resolve  function  has  the	same  behavior	as  in	regis-

       send(Name, Msg) -> Pid


		 Name =	Msg = term()
		 Pid = pid()

	      Sends the	message	Msg to the pid globally	registered as Name.

	      Failure: If Name is not a	globally registered name, the  calling
	      function will exit with reason {badarg, {Name, Msg}}.

       set_lock(Id) -> boolean()

       set_lock(Id, Nodes) -> boolean()

       set_lock(Id, Nodes, Retries) -> boolean()


		 Id = id()
		 Nodes = [node()]
		 Retries = retries()
		 id() =	{ResourceId :: term(), LockRequesterId :: term()}
		 retries() = integer() >= 0 | infinity

	      Sets  a lock on the specified nodes (or on all nodes if none are
	      specified) on ResourceId for LockRequesterId. If a lock  already
	      exists on	ResourceId for another requester than LockRequesterId,
	      and Retries is not equal to 0, the process sleeps	 for  a	 while
	      and  will	try to execute the action later. When Retries attempts
	      have been	made, false is returned, otherwise true. If Retries is
	      infinity,	 true is eventually returned (unless the lock is never

	      If no value for Retries is given,	infinity is used.

	      This function is completely synchronous.

	      If a process which holds a lock dies, or the node	goes down, the
	      locks held by the	process	are deleted.

	      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.

	      This  function  does  not	 address  the problem of a deadlock. A
	      deadlock can never occur as long as processes only lock one  re-
	      source  at a time. But if	some processes try to lock two or more
	      resources, a deadlock may	occur. It is up	to the application  to
	      detect and rectify a deadlock.

	      Some  values  of ResourceId should be avoided or Erlang/OTP will
	      not work	properly.  A  list  of	resources  to  avoid:  global,
	      dist_ac, mnesia_table_lock, mnesia_adjust_log_writes, pg2.

       sync() -> ok | {error, Reason ::	term()}

	      Synchronizes the global name server with all nodes known to this
	      node.  These  are	 the  nodes  which  are	 returned   from   er-
	      lang:nodes(). When this function returns,	the global name	server
	      will receive global information from all	nodes.	This  function
	      can be called when new nodes are added to	the network.

	      The only possible	error reason Reason is {"global_groups defini-
	      tion error", Error}.

       trans(Id, Fun) -> Res | aborted

       trans(Id, Fun, Nodes) ->	Res | aborted

       trans(Id, Fun, Nodes, Retries) -> Res | aborted


		 Id = id()
		 Fun = trans_fun()
		 Nodes = [node()]
		 Retries = retries()
		 Res = term()
		 retries() = integer() >= 0 | infinity
		 trans_fun() = function() | {module(), atom()}

	      Sets a lock on Id	(using set_lock/3). If this succeeds, Fun() is
	      evaluated	and the	result Res is returned.	Returns	aborted	if the
	      lock attempt failed. If Retries is set to	infinity, the transac-
	      tion will	not abort.

	      infinity	is the default setting and will	be used	if no value is
	      given for	Retries.

       unregister_name(Name) ->	term()


		 Name =	term()

	      Removes the globally registered name Name	from  the  network  of
	      Erlang nodes.

       whereis_name(Name) -> pid() | undefined


		 Name =	term()

	      Returns  the pid with the	globally registered name Name. Returns
	      undefined	if the name is not globally registered.

       global_group(3),	net_kernel(3)

Ericsson AB			  kernel 3.2			     global(3)


Want to link to this manual page? Use this URL:

home | help