Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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

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

              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) -> 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:    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  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 register_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
              application 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 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 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) -> 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)