global_group(3)



global_group(3erl)         Erlang Module Definition         global_group(3erl)

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 run-
           ning on each node. The processes are automatically started and syn-
           chronized when a node is started.

         * All  involved nodes must agree on the global group definition, oth-
           erwise 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 con-
              nections 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 unde-
              fined.

                {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  sub-
                  scribed 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 discon-
              nects, respectively.

       own_nodes() -> Nodes

              Types:

                 Nodes = [Node :: node()]

              Returns  the  names of all group nodes, regardless of their cur-
              rent 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 pro-
              vided)  in  any  global group. The global groups are searched in
              the order that they appear in the value of configuration parame-
              ter 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 pro-
              vided) in any global group. The global groups  are  searched  in
              the order that they appear in the value of configuration parame-
              ter 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 pre-
           vents this to be done, but the application code  must  then  handle
           the situation.

SEE ALSO
       global(3erl), erl(1)

Ericsson AB                       kernel 7.0                global_group(3erl)

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