Provided by: erlang-manpages_22.0.7+dfsg-1_all bug

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 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_all false 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.

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 refer 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 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  (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 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_lock

                * pg2

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

SEE ALSO

       global_group(3erl), net_kernel(3erl)