global(14)



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

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 pro-
       gramming  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 re-
       sulting 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 glob-
       ally 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 vari-
       ables   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  registra-
       tion service cannot be used, but the lock mechanism still works.

       If  the global name server fails to connect nodes (N1 and N3 in the ex-
       ample), 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 in-
       crease 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 re-
              fer 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 compatibil-
                   ity, but its use is deprecated.

              Globally  associates name Name with a pid, that is, globally no-
              tifies 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 func-
              tion  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 ex-
              ample, no is returned if an attempt is made to register  an  al-
              ready  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 re-
              source at a time. A deadlock can occur if some processes try  to
              lock  two  or more resources. It is up to the application to de-
              tect 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 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 fails. If Retries is set to infinity, the  transac-
              tion does not abort.

              infinity is the default setting and is used if no value is spec-
              ified 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)

Ericsson AB                       kernel 7.0                      global(3erl)

Man(1) output converted with man2html
list of all man pages