Unix/Linux Go Back    


Linux 2.6 - man page for global (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


global(3erl)			     Erlang Module Definition			     global(3erl)

NAME
       global - A Global Name Registration Facility

DESCRIPTION
       This documentation describes the Global module which consists of the following functional-
       ities:

	 * 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 programming of distrib-
       uted  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 regis-
       tered  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 unregis-
       tered.

       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 globally registered process goes  down,  the
       name  will  be  globally  unregistered.	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(7) .

       The name server will also maintain a fully connected network. For example, if node N1 con-
       nects 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 warn-
       ing  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 prob-
       lem 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 .

EXPORTS
       del_lock(Id)
       del_lock(Id, Nodes) -> void()

	      Types  Id = {ResourceId, LockRequesterId}
		     ResourceId = term()
		     LockRequesterId = term()
		     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 register_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) -> Pid1 | Pid2

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

	      This  function  can  be  used  as a name resolving function for register_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) -> Pid1 | Pid2

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

	      This  function  can  be  used  as a name resolving function for register_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)
       register_name(Name, Pid, Resolve) -> yes | no

	      Types  Name = term()
		     Pid = pid()
		     Resolve = fun() or {Module, Function} where
		     Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none

	      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  regis-
	      tered 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  func-
	      tion is called once for each name clash.

	      There   are   three   pre-defined  resolve  functions:  random_exit_name/3  ,  ran-
	      dom_notify_name/3 , and notify_all_name/3 . If no Resolve function is defined, ran-
	      dom_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)
       re_register_name(Name, Pid, Resolve) -> void()

	      Types  Name = term()
		     Pid = pid()
		     Resolve = fun() or {Module, Function} where
		     Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none

	      Atomically changes the registered name Name on all nodes to refer to Pid .

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

       send(Name, Msg) -> Pid

	      Types  Name = term()
		     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)
       set_lock(Id, Nodes)
       set_lock(Id, Nodes, Retries) -> boolean()

	      Types  Id = {ResourceId, LockRequesterId}
		     ResourceId = term()
		     LockRequesterId = term()
		     Nodes = [node()]
		     Retries = int() >= 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() -> void()

	      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.

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

	      Types  Id = {ResourceId, LockRequesterId}
		     ResourceId = term()
		     LockRequesterId = term()
		     Fun = fun() | {M, F}
		     Nodes = [node()]
		     Retries = int() >= 0 | infinity
		     Res = term()

	      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 transaction will not abort.

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

       unregister_name(Name) -> void()

	      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(3erl) , net_kernel(3erl)

Ericsson AB				  kernel 2.14.3 			     global(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:34 PM.