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

FreeBSD Manual Pages

  
 
  

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

NAME
       global -	A global name registration facility.

DESCRIPTION
       This module consists of the following services:

	 * Registration	of global names

	 * Global locks

	 * Maintenance of the fully connected network

       These  services	are  controlled	through	the process global_name_server
       that exists on every node. The global name server starts	 automatically
       when  a	node  is  started. With	the term global	is meant over a	system
       consisting of many 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
       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.

       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 re-
       sulting 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 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.

       Both  the registration and lock services	are atomic. All	nodes involved
       in these	actions	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 that runs a glob-
       ally registered process goes down, the name is  globally	 unregistered.
       To  this	 end, the global name server subscribes	to nodeup and nodedown
       messages	sent from module net_kernel. Relevant Kernel application vari-
       ables   in   this   context   are   net_setuptime,   net_ticktime,  and
       dist_auto_connect. See also kernel(6).

       The name	server also maintains a	fully connected	network. For  example,
       if  node	N1 connects to node N2 (which is already connected to N3), the
       global name servers on the nodes	N1 and N3 ensure that also N1  and  N3
       are  connected.	If this	is not desired,	command-line flag -connect_all
       false can be used (see also erl(1)). In this case, the  name  registra-
       tion service cannot be used, but	the lock mechanism still works.

       If  the global name server fails	to connect nodes (N1 and N3 in the ex-
       ample), 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 rpc:call(N1, net_adm, ping,	[N2])  in  the	Erlang
       shell), but it indicates	a network problem.

   Note:
       If the fully connected network is not set up properly, try first	to in-
       crease the value	of net_setuptime.

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

EXPORTS
       del_lock(Id) -> true

       del_lock(Id, Nodes) -> true

	      Types:

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

	      Deletes the lock Id synchronously.

       notify_all_name(Name, Pid1, Pid2) -> none

	      Types:

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

	      Can be used as a name resolving function for register_name/3 and
	      re_register_name/3.

	      The  function  unregisters  both	pids  and  sends  the  message
	      {global_name_conflict, Name, OtherPid} to	both processes.

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

	      Types:

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

	      Can be used as a name resolving function for register_name/3 and
	      re_register_name/3.

	      The  function  randomly selects one of the pids for registration
	      and kills	the other one.

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

	      Types:

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

	      Can be used as a name resolving function for register_name/3 and
	      re_register_name/3.

	      The  function randomly selects one of the	pids for registration,
	      and sends	the message {global_name_conflict, Name} to the	 other
	      pid.

       re_register_name(Name, Pid) -> yes

       re_register_name(Name, Pid, Resolve) -> yes

	      Types:

		 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.

	      Function Resolve has the same behavior as	in register_name/2,3.

       register_name(Name, Pid)	-> yes | no

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

	      Types:

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

	      Globally	associates name	Name with a pid, that is, globally no-
	      tifies all nodes of a new	global name in	a  network  of	Erlang
	      nodes.

	      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	Resolve	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.

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

	      Three  predefined	 resolve  functions exist: random_exit_name/3,
	      random_notify_name/3, and	notify_all_name/3. If no Resolve func-
	      tion  is	defined, random_exit_name is used. This	means that one
	      of the two registered processes is selected as correct while the
	      other is killed.

	      This  function  is  completely  synchronous,  that is, 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.

	  Note:
	      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
	      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]

	      Types:

		 Name =	term()

	      Returns a	list of	all globally registered	names.

       send(Name, Msg) -> Pid

	      Types:

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

	      Sends message Msg	to the pid globally registered as Name.

	      If  Name is not a	globally registered name, the calling function
	      exits with reason	{badarg, {Name,	Msg}}.

       set_lock(Id) -> boolean()

       set_lock(Id, Nodes) -> boolean()

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

	      Types:

		 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 tries	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
	      released).

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

	      This function is completely synchronous.

	      If  a process that 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.	A deadlock can occur if	some processes try  to
	      lock  two	 or more resources. It is up to	the application	to de-
	      tect and rectify a deadlock.

	  Note:
	      Avoid the	following values of ResourceId,	 otherwise  Erlang/OTP
	      does not work properly:

		* dist_ac

		* global

		* mnesia_adjust_log_writes

		* mnesia_table_lock

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

	      Synchronizes the global name server with all nodes known to this
	      node. These are the nodes	that are returned from erlang:nodes().
	      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.

	      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

	      Types:

		 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 fails. If Retries is	set to infinity, the  transac-
	      tion does	not abort.

	      infinity is the default setting and is used if no	value is spec-
	      ified for	Retries.

       unregister_name(Name) ->	term()

	      Types:

		 Name =	term()

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

       whereis_name(Name) -> pid() | undefined

	      Types:

		 Name =	term()

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

SEE ALSO
       global_group(3),	net_kernel(3)

Ericsson AB			  kernel 8.2			     global(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=global&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help