global - A global name registration facility.

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

       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 programming 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
       resulting 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  globally  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 variables in this context are net_setuptime, net_ticktime,
       and dist_auto_connect. See also kernel(7).

       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_allfalse can be used (see  also
       erl(1)). In this case, the name registration service cannot be used, but the lock mechanism still works.

       If  the  global name server fails to connect nodes (N1 and N3 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 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 increase the value of net_setuptime.

del_lock(Id)->truedel_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)->yesre_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.

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

       register_name(Name,Pid)->yes|noregister_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 compatibility, but its use is deprecated.

              Globally associates 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,  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 (funModule: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 function 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 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 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 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.

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

                * dist_ac

                * global

                * mnesia_adjust_log_writes

                * mnesia_table_locksync()->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_groupsdefinitionerror",Error}.

       trans(Id,Fun)->Res|abortedtrans(Id,Fun,Nodes)->Res|abortedtrans(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
              transaction does not abort.

              infinity is the default setting and is used if no value is specified 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.

       global - A global name registration facility.

global_group(3erl), net_kernel(3erl)

Ericsson AB                                        kernel 8.2                                       global(3erl)