.TH global_group 3erl "kernel 5.1.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
global_group \- Grouping nodes to global name registration groups.
.SH DESCRIPTION
.LP
This module makes it possible to partition the nodes of a system into \fIglobal groups\fR\&\&. Each global group has its own global namespace, see \fB\fIglobal(3erl)\fR\&\fR\&\&.
.LP
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\&.
.LP
The Kernel configuration parameter \fIglobal_groups\fR\& defines the global groups (see also \fB\fIkernel(7)\fR\&\fR\& and \fB\fIconfig(5)\fR\&\fR\&):
.LP
.nf

{global_groups, [GroupTuple :: group_tuple()]}
.fi
.LP
For the processes and nodes to run smoothly using the global group functionality, the following criteria must be met:
.RS 2
.TP 2
*
An instance of the global group server, \fIglobal_group\fR\&, must be running on each node\&. The processes are automatically started and synchronized when a node is started\&.
.LP
.TP 2
*
All involved nodes must agree on the global group definition, otherwise the behavior of the system is undefined\&.
.LP
.TP 2
*
\fIAll\fR\& nodes in the system must belong to exactly one global group\&.
.LP
.RE

.LP
In the following descriptions, a \fIgroup node\fR\& is a node belonging to the same global group as the local node\&.
.SH DATA TYPES
.nf

\fBgroup_tuple()\fR\& = 
.br
    {GroupName :: \fBgroup_name()\fR\&, [node()]} |
.br
    {GroupName :: \fBgroup_name()\fR\&,
.br
     PublishType :: \fBpublish_type()\fR\&,
.br
     [node()]}
.br
.fi
.RS
.LP
A \fIGroupTuple\fR\& without \fIPublishType\fR\& is the same as a \fIGroupTuple\fR\& with \fIPublishType\fR\& equal to \fInormal\fR\&\&.
.RE

.nf

\fBgroup_name()\fR\& = atom()
.br
.fi
.nf

\fBpublish_type()\fR\& = hidden | normal
.br
.fi
.RS
.LP
A node started with command-line flag \fI-hidden\fR\& (see \fB\fIerl(1)\fR\&\fR\&) is said to be a \fIhidden\fR\& 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\&.
.LP
A global group defined with \fIPublishType\fR\& equal to \fIhidden\fR\& 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 \fI-hidden\fR\& or not\&.
.RE

.nf

\fBname()\fR\& = atom()
.br
.fi
.RS
.LP
A registered name\&.
.RE

.nf

\fBwhere()\fR\& = {node, node()} | {group, \fBgroup_name()\fR\&}
.br
.fi
.SH EXPORTS
.LP
.nf

.B
global_groups() -> {GroupName, GroupNames} | undefined
.br
.fi
.br
.RS
.LP
Types:

.RS 3
GroupName = \fBgroup_name()\fR\&
.br
GroupNames = [GroupName]
.br
.RE
.RE
.RS
.LP
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 \fIundefined\fR\& if no global groups are defined\&.
.RE

.LP
.nf

.B
info() -> [info_item()]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
.nf
\fBinfo_item()\fR\& = 
.br
    {state, State :: \fBsync_state()\fR\&} |
.br
    {own_group_name, GroupName :: \fBgroup_name()\fR\&} |
.br
    {own_group_nodes, Nodes :: [node()]} |
.br
    {synched_nodes, Nodes :: [node()]} |
.br
    {sync_error, Nodes :: [node()]} |
.br
    {no_contact, Nodes :: [node()]} |
.br
    {other_groups, Groups :: [\fBgroup_tuple()\fR\&]} |
.br
    {monitoring, Pids :: [pid()]}
.fi
.br
.nf
\fBsync_state()\fR\& = no_conf | synced
.fi
.br
.RE
.RE
.RS
.LP
Returns a list containing information about the global groups\&. Each list element is a tuple\&. The order of the tuples is undefined\&.
.RS 2
.TP 2
.B
\fI{state, State}\fR\&:
If the local node is part of a global group, \fIState\fR\& is equal to \fIsynced\fR\&\&. If no global groups are defined, \fIState\fR\& is equal to \fIno_conf\fR\&\&.
.TP 2
.B
\fI{own_group_name, GroupName}\fR\&:
The name (atom) of the group that the local node belongs to\&.
.TP 2
.B
\fI{own_group_nodes, Nodes}\fR\&:
A list of node names (atoms), the group nodes\&.
.TP 2
.B
\fI{synced_nodes, Nodes}\fR\&:
A list of node names, the group nodes currently synchronized with the local node\&.
.TP 2
.B
\fI{sync_error, Nodes}\fR\&:
A list of node names, the group nodes with which the local node has failed to synchronize\&.
.TP 2
.B
\fI{no_contact, Nodes}\fR\&:
A list of node names, the group nodes to which there are currently no connections\&.
.TP 2
.B
\fI{other_groups, Groups}\fR\&:
\fIGroups\fR\& is a list of tuples \fI{GroupName, Nodes}\fR\&, specifying the name and nodes of the other global groups\&.
.TP 2
.B
\fI{monitoring, Pids}\fR\&:
A list of pids, specifying the processes that have subscribed to \fInodeup\fR\& and \fInodedown\fR\& messages\&.
.RE
.RE

.LP
.nf

.B
monitor_nodes(Flag) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Flag = boolean()
.br
.RE
.RE
.RS
.LP
Depending on \fIFlag\fR\&, the calling process starts subscribing (\fIFlag\fR\& equal to \fItrue\fR\&) or stops subscribing (\fIFlag\fR\& equal to \fIfalse\fR\&) to node status change messages\&.
.LP
A process that has subscribed receives the messages \fI{nodeup, Node}\fR\& and \fI{nodedown, Node}\fR\& when a group node connects or disconnects, respectively\&.
.RE

.LP
.nf

.B
own_nodes() -> Nodes
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [Node :: node()]
.br
.RE
.RE
.RS
.LP
Returns the names of all group nodes, regardless of their current status\&.
.RE

.LP
.nf

.B
registered_names(Where) -> Names
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Where = \fBwhere()\fR\&
.br
Names = [Name :: \fBname()\fR\&]
.br
.RE
.RE
.RS
.LP
Returns a list of all names that are globally registered on the specified node or in the specified global group\&.
.RE

.LP
.nf

.B
send(Name, Msg) -> pid() | {badarg, {Name, Msg}}
.br
.fi
.br
.nf

.B
send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Where = \fBwhere()\fR\&
.br
Name = \fBname()\fR\&
.br
Msg = term()
.br
.RE
.RE
.RS
.LP
Searches for \fIName\fR\&, globally registered on the specified node or in the specified global group, or (if argument \fIWhere\fR\& is not provided) in any global group\&. The global groups are searched in the order that they appear in the value of configuration parameter \fIglobal_groups\fR\&\&.
.LP
If \fIName\fR\& is found, message \fIMsg\fR\& 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 \fI{badarg, {Name, Msg}}\fR\&\&.
.RE

.LP
.nf

.B
sync() -> ok
.br
.fi
.br
.RS
.LP
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\&.
.LP
If synchronization is not possible, an error report is sent to the error logger (see also \fB\fIerror_logger(3erl)\fR\&\fR\&\&.
.LP
Returns \fI{error, {\&'invalid global_groups definition\&', Bad}}\fR\& if configuration parameter \fIglobal_groups\fR\& has an invalid value \fIBad\fR\&\&.
.RE

.LP
.nf

.B
whereis_name(Name) -> pid() | undefined
.br
.fi
.br
.nf

.B
whereis_name(Where, Name) -> pid() | undefined
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Where = \fBwhere()\fR\&
.br
Name = \fBname()\fR\&
.br
.RE
.RE
.RS
.LP
Searches for \fIName\fR\&, globally registered on the specified node or in the specified global group, or (if argument \fIWhere\fR\& is not provided) in any global group\&. The global groups are searched in the order that they appear in the value of configuration parameter \fIglobal_groups\fR\&\&.
.LP
If \fIName\fR\& is found, the corresponding pid is returned\&. If the name is not found, the function returns \fIundefined\fR\&\&.
.RE

.SH "NOTES"

.RS 2
.TP 2
*
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\&.
.LP
.TP 2
*
Function \fB\fIsend/2,3\fR\&\fR\& is not secure\&.
.LP
.TP 2
*
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\&.
.LP
.RE

.SH "SEE ALSO"

.LP
\fB\fIglobal(3erl)\fR\&\fR\&, \fB\fIerl(1)\fR\&\fR\&