From 3d70cee4034e4da37d125679345aa2a10c58cb34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 14 Apr 2015 23:21:36 +0200 Subject: Update Kernel documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by technical writers from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/kernel/doc/src/global_group.xml | 175 ++++++++++++++++++++---------------- 1 file changed, 98 insertions(+), 77 deletions(-) (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 index 4b21b0a14a..8f947b9adf 100644 --- a/lib/kernel/doc/src/global_group.xml +++ b/lib/kernel/doc/src/global_group.xml @@ -4,7 +4,7 @@
- 19982013 + 19982016 Ericsson AB. All Rights Reserved. @@ -26,22 +26,22 @@ Esko Vierumäki 1998-12-18 - b + B
global_group - Grouping Nodes to Global Name Registration Groups + 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 +

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

+

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), - config(4):

+ kernel(6) + and config(4)):

{global_groups, [GroupTuple :: group_tuple()]}

For the processes and nodes to run smoothly using the global @@ -54,22 +54,24 @@

All involved nodes must agree on the global group definition, - or the behavior of the system is undefined.

+ otherwise the behavior of the system is undefined.

-

All nodes in the system should belong to exactly +

All nodes in the system must belong to exactly one global group.

 -

In the following description, a group node is a node +

In the following descriptions, a group node is a node belonging to the same global group as the local node.

 - + +

A GroupTuple without PublishType is the same as a - GroupTuple with PublishType == normal.

+ GroupTuple with PublishType equal to normal. +

@@ -78,52 +80,57 @@ -

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 +

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 == 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.

+

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.

A registered name.

 + + - Return the global group names + Return the global group names. -

Returns a tuple containing the name of the global group +

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.

 + - Information about global groups + Information about global groups.

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.

+ 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 == synced. If no global groups are defined, - State == no_conf.

+ State is equal to synced. + If no global groups are defined, + State is equal to no_conf.

 {own_group_name, GroupName} @@ -152,117 +159,131 @@ {other_groups, Groups}

Groups is a list of tuples - {GroupName, Nodes}, specifying the name and nodes + {GroupName, Nodes}, + specifying the name and nodes of the other global groups.

 {monitoring, Pids} -

A list of pids, specifying the processes which have +

A list of pids, specifying the processes that have subscribed to nodeup and nodedown messages.

 + - Subscribe to node status changes + Subscribe to node status changes. -

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 +

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.

 + - Return the group nodes + Return the group nodes.

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

 + - Return globally registered names + Return globally registered names. -

Returns a list of all names which are globally registered +

Returns a list of all names that are globally registered on the specified node or in the specified global group.

 + - Send a message to a globally registered pid + Send a message to a globally registered pid.

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 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}}.

 + - Synchronize the group nodes + Synchronize the group nodes.

Synchronizes the group nodes, that is, the global name - servers on the group nodes. Also check the names globally + 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(3)).

-

Failure: - {error, {'invalid global_groups definition', Bad}} if - the global_groups configuration parameter has an + to the error logger (see also + error_logger(3). +

+

Returns {error, {'invalid global_groups definition', Bad}} + if configuration parameter global_groups has an invalid value Bad.

 + - Get the pid with a given globally registered name + Get the pid with a specified globally registered 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 + 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.
- 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.

+ 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 -

erl(1), - global(3)

+ See Also +

global(3), + erl(1)

 -- cgit v1.2.3