View Source global_group (kernel v9.3)
Grouping nodes to global name registration groups.
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
.
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(6)
and
config(4)
):
{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.
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
Summary
Types
A GroupTuple
without PublishType
is the same as a GroupTuple
with
PublishType
equal to normal
.
A registered name.
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.
Functions
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.
Returns a list containing information about the global groups. Each list element is a tuple. The order of the tuples is undefined.
Depending on Flag
, the calling process starts subscribing (Flag
equal to
true
) or stops subscribing (Flag
equal to false
) to node status change
messages.
Returns the names of all group nodes, regardless of their current status.
Returns a list of all names that are globally registered on the specified node or in the specified global group.
Equivalent to send/3
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
.
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.
Equivalent to whereis_name/2
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
.
Types
-type group_name() :: atom().
-type 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
.
-type 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()]}.
-type name() :: atom().
A registered name.
-type 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.
-type sync_state() :: no_conf | synced.
-type where() :: {node, node()} | {group, group_name()}.
Functions
-spec global_groups() -> {GroupName, GroupNames} | undefined when 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.
-spec info() -> [info_item()].
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 tosynced
. If no global groups are defined,State
is equal tono_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 tonodeup
andnodedown
messages.
-spec monitor_nodes(Flag) -> ok when 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.
-spec own_nodes() -> Nodes when Nodes :: [Node :: node()].
Returns the names of all group nodes, regardless of their current status.
Returns a list of all names that are globally registered on the specified node or in the specified global group.
Equivalent to send/3
-spec send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}} when 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}}
.
-spec 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
.
Returns {error, {'invalid global_groups definition', Bad}}
if configuration
parameter global_groups
has an invalid value Bad
.
Equivalent to whereis_name/2
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
.