From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/kernel/doc/src/global_group.xml | 284 ++++++++++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 lib/kernel/doc/src/global_group.xml (limited to 'lib/kernel/doc/src/global_group.xml') diff --git a/lib/kernel/doc/src/global_group.xml b/lib/kernel/doc/src/global_group.xml new file mode 100644 index 0000000000..4facf4a4aa --- /dev/null +++ b/lib/kernel/doc/src/global_group.xml @@ -0,0 +1,284 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + global_group + Esko Vierumäki + + 1998-12-18 + b +
+ global_group + Grouping Nodes to Global Name Registration Groups + +

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(3). 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(6), + config(4):

+ +{global_groups, [GroupTuple]} +

Types:

+ + GroupTuple = {GroupName, [Node]} | {GroupName, PublishType, [Node]} + GroupName = atom() (naming a global group) + PublishType = normal | hidden + Node = atom() (naming a node) + +

A GroupTuple without PublishType is the same as a + GroupTuple with PublishType == 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.

+

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.

+ + + + global_groups() -> {GroupName, GroupNames} | undefined + Return the global group names + + GroupName = atom() + 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() -> [{Item, Info}] + Information about global groups + + Item, Info -- see below + + +

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 + Subscribe to node status changes + + Flag = bool() + + +

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 + Return the group nodes + + Nodes = [Node] +  Node = node() + + +

Returns the names of all group nodes, regardless of their + current status.

+ + + + registered_names(Where) -> Names + Return globally registered names + + Where = {node, Node} | {group, GroupName} +  Node = node() +  GroupName = atom() + Names = [Name] +  Name = atom() + + +

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}} + Send a message to a globally registered pid + + Where = {node, Node} | {group, GroupName} +  Node = node() +  GroupName = atom() + Name = atom() + 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 + Synchronize the group nodes + +

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(3)).

+

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 + Get the pid with a given globally registered name + + Where = {node, Node} | {group, GroupName} +  Node = node() +  GroupName = atom() + Name = atom() + + +

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(3)

+
+ + -- cgit v1.2.3