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

NAME

       global_group - Grouping Nodes to Global Name Registration Groups

DESCRIPTION

       The  global  group  function  makes  it  possible  to  group  the  nodes  in a system into
       partitions, each partition having its own global name space, refer to global(3erl).  These
       partitions are called global groups.

       The  main  advantage  of  dividing  systems  to  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), 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, or the behavior  of  the
           system is undefined.

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

       In the following description, 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  ==
              normal.

       group_name() = atom()

       publish_type() = hidden | normal

              A  node  started  with  the  command line flag -hidden, see erl(1), is said to be a
              hidden node. A hidden node will establish 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 == hidden, is said to be  a  hidden  global
              group.  All nodes in a hidden global group are hidden nodes, regardless if they are
              started with the -hidden command line flag 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 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 element of  the
              list is a tuple. The order of the tuples is not defined.

                {state, State}:
                  If  the  local  node  is  part of a global group, State == synced. If no global
                  groups are defined, State == 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 which have subscribed  to  nodeup  and
                  nodedown messages.

       monitor_nodes(Flag) -> ok

              Types:

                 Flag = boolean()

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

              A process which has  subscribed  will  receive  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 which 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 the Where argument is not provided -- in any global group.
              The global groups are searched in the order in which they appear in  the  value  of
              the global_groups configuration parameter.

              If Name is found, the 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  check  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)).

              Failure: {error, {'invalid global_groups definition', Bad}}  if  the  global_groups
              configuration parameter 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 the Where argument is not provided -- in any  global  group.
              The  global  groups  are searched in the order in which they appear in the value of
              the global_groups configuration parameter.

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

NOTE

       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
       may produce an incorrect or misleading result. For example, the isolated node may not have
       accurate information about registered names in its global group.

       Note also that the send/2,3 function is not secure.

       Distribution of applications is highly dependent of the global group  definitions.  It  is
       not  recommended  that  an  application  is  distributed over several global groups of the
       obvious reason that the  registered  names  may  be  moved  to  another  global  group  at
       failover/takeover.  There  is nothing preventing doing this, but the application code must
       in such case handle the situation.

SEE ALSO

       erl(1), global(3erl)