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)