Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
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)