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

NAME

       global_group - Grouping nodes to global name registration groups.

DESCRIPTION

       This  module makes it possible to partition the nodes of a system into global groups. Each
       global group has its own global namespace, see global(3erl).

       The main advantage of dividing systems into global groups  is  that  the  background  load
       decreases  while  the  number of nodes to be updated is reduced when manipulating globally
       registered names.

       The Kernel configuration parameter global_groups  defines  the  global  groups  (see  also
       kernel(7) and config(5)):

       {global_groups, [GroupTuple :: group_tuple()]}

       For  the  processes  and  nodes  to run smoothly using the global group functionality, the
       following criteria must be met:

         * An instance of the global group server, global_group, must be running  on  each  node.
           The processes are automatically started and synchronized when a node is started.

         * All  involved  nodes must agree on the global group definition, otherwise the behavior
           of the system is undefined.

         * All nodes in the system must belong to exactly one global group.

       In the following descriptions, a group node is a node belonging to the same  global  group
       as the local node.

DATA TYPES

       group_tuple() =
           {GroupName :: group_name(), [node()]} |
           {GroupName :: group_name(),
            PublishType :: publish_type(),
            [node()]}

              A GroupTuple without PublishType is the same as a GroupTuple with PublishType equal
              to normal.

       group_name() = atom()

       publish_type() = hidden | normal

              A node started with command-line flag -hidden (see erl(1)) is said to be  a  hidden
              node.  A  hidden  node establishes hidden connections to nodes not part of the same
              global group, but normal (visible) connections to nodes part  of  the  same  global
              group.

              A  global  group  defined  with  PublishType equal to hidden is said to be a hidden
              global group. All nodes in a hidden global group are hidden nodes, whether they are
              started with command-line flag -hidden or not.

       name() = atom()

              A registered name.

       where() = {node, node()} | {group, group_name()}

EXPORTS

       global_groups() -> {GroupName, GroupNames} | undefined

              Types:

                 GroupName = group_name()
                 GroupNames = [GroupName]

              Returns a tuple containing the name of the global group that the local node belongs
              to, and the list of all other known group names. Returns  undefined  if  no  global
              groups are defined.

       info() -> [info_item()]

              Types:

                 info_item() =
                     {state, State :: sync_state()} |
                     {own_group_name, GroupName :: group_name()} |
                     {own_group_nodes, Nodes :: [node()]} |
                     {synched_nodes, Nodes :: [node()]} |
                     {sync_error, Nodes :: [node()]} |
                     {no_contact, Nodes :: [node()]} |
                     {other_groups, Groups :: [group_tuple()]} |
                     {monitoring, Pids :: [pid()]}
                 sync_state() = no_conf | synced

              Returns a list containing information about the global groups. Each list element is
              a tuple. The order of the tuples is undefined.

                {state, State}:
                  If the local node is part of a global group, State is equal to  synced.  If  no
                  global groups are defined, State is equal to no_conf.

                {own_group_name, GroupName}:
                  The name (atom) of the group that the local node belongs to.

                {own_group_nodes, Nodes}:
                  A list of node names (atoms), the group nodes.

                {synced_nodes, Nodes}:
                  A  list  of  node  names, the group nodes currently synchronized with the local
                  node.

                {sync_error, Nodes}:
                  A list of node names, the group nodes with which the local node has  failed  to
                  synchronize.

                {no_contact, Nodes}:
                  A  list  of  node  names,  the  group  nodes  to  which  there are currently no
                  connections.

                {other_groups, Groups}:
                  Groups is a list of tuples {GroupName, Nodes}, specifying the name and nodes of
                  the other global groups.

                {monitoring, Pids}:
                  A  list  of  pids,  specifying the processes that have subscribed to nodeup and
                  nodedown messages.

       monitor_nodes(Flag) -> ok

              Types:

                 Flag = boolean()

              Depending on Flag, the calling process starts subscribing (Flag equal to  true)  or
              stops subscribing (Flag equal to false) to node status change messages.

              A  process  that has subscribed receives the messages {nodeup, Node} and {nodedown,
              Node} when a group node connects or disconnects, respectively.

       own_nodes() -> Nodes

              Types:

                 Nodes = [Node :: node()]

              Returns the names of all group nodes, regardless of their current status.

       registered_names(Where) -> Names

              Types:

                 Where = where()
                 Names = [Name :: name()]

              Returns a list of all names that are globally registered on the specified  node  or
              in the specified global group.

       send(Name, Msg) -> pid() | {badarg, {Name, Msg}}

       send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}

              Types:

                 Where = where()
                 Name = name()
                 Msg = term()

              Searches  for  Name,  globally registered on the specified node or in the specified
              global group, or (if argument Where is not  provided)  in  any  global  group.  The
              global  groups  are  searched  in  the  order  that  they  appear  in  the value of
              configuration parameter global_groups.

              If Name is found, message Msg is sent to the corresponding pid. The pid is also the
              return  value  of  the  function.  If  the  name is not found, the function returns
              {badarg, {Name, Msg}}.

       sync() -> ok

              Synchronizes the group nodes, that is, the global name servers on the group  nodes.
              Also  checks  the  names  globally  registered  in  the  current  global  group and
              unregisters them on any known node not part of the group.

              If synchronization is not possible, an error report is sent  to  the  error  logger
              (see also error_logger(3erl).

              Returns   {error,  {'invalid  global_groups  definition',  Bad}}  if  configuration
              parameter global_groups has an invalid value Bad.

       whereis_name(Name) -> pid() | undefined

       whereis_name(Where, Name) -> pid() | undefined

              Types:

                 Where = where()
                 Name = name()

              Searches for Name, globally registered on the specified node or  in  the  specified
              global  group,  or  (if  argument  Where  is not provided) in any global group. The
              global groups are  searched  in  the  order  that  they  appear  in  the  value  of
              configuration parameter global_groups.

              If  Name is found, the corresponding pid is returned. If the name is not found, the
              function returns undefined.

NOTES

         * In the situation where a node has lost its connections to other nodes  in  its  global
           group,  but  has  connections  to nodes in other global groups, a request from another
           global group can produce an incorrect or misleading result. For example, the  isolated
           node can have inaccurate information about registered names in its global group.

         * Function send/2,3 is not secure.

         * Distribution  of  applications is highly dependent of the global group definitions. It
           is not recommended that an application is distributed over many global groups, as  the
           registered  names  can  be moved to another global group at failover/takeover. Nothing
           prevents this to be done, but the application code must then handle the situation.

SEE ALSO

       global(3erl), erl(1)