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  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
       application 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
       work.

       If  the	global	name  server  fails to connect nodes (N1 and N3	in the
       example above) a	warning	event is sent to the error logger.  The	 pres-
       ence  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.

   Note:
       If the fully connected network is not set up properly, the first	 thing
       to try is to increase 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()

	      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()

	      Types:

		 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()

	      Types:

		 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

	      Types:

		 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
	      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, 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
	      clash.

	  Warning:
	      If  you  plan to change code without restarting your system, you
	      must use an external  fun	 (fun  Module:Function/Arity)  as  the
	      Resolve  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
	      example,	no  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.

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

	      Types:

		 Name =	term()

	      Returns a	lists of all globally registered names.

       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
	      refer to Pid.

	      The  Resolve  function  has  the	same  behavior	as  in	regis-
	      ter_name/2,3.

       send(Name, Msg) -> Pid

	      Types:

		 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()

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

	      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
	      resource	at  a  time.  But if some processes try	to lock	two or
	      more resources, a	deadlock may occur. It is up to	 the  applica-
	      tion to detect and rectify a deadlock.

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

	      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 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()

	      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 3.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+12.0-RELEASE+and+Ports>

home | help