aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/global_group.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/global_group.xml')
-rw-r--r--lib/kernel/doc/src/global_group.xml175
1 files changed, 98 insertions, 77 deletions
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 @@
<erlref>
<header>
<copyright>
- <year>1998</year><year>2013</year>
+ <year>1998</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -26,22 +26,22 @@
<prepared>Esko Vierum&auml;ki</prepared>
<docno></docno>
<date>1998-12-18</date>
- <rev>b</rev>
+ <rev>B</rev>
</header>
<module>global_group</module>
- <modulesummary>Grouping Nodes to Global Name Registration Groups</modulesummary>
+ <modulesummary>Grouping nodes to global name registration groups.</modulesummary>
<description>
- <p>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 <c>global(3)</c>. These partitions are
- called global groups.</p>
- <p>The main advantage of dividing systems to global groups is that
+ <p>This module makes it possible to partition the nodes of a
+ system into <em>global groups</em>. Each global group has its own
+ global namespace, see <seealso marker="global">
+ <c>global(3)</c></seealso>.</p>
+ <p>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.</p>
<p>The Kernel configuration parameter <c>global_groups</c> defines
the global groups (see also
- <seealso marker="kernel_app">kernel(6)</seealso>,
- <seealso marker="config">config(4)</seealso>:</p>
+ <seealso marker="kernel_app#global_groups"><c>kernel(6)</c></seealso>
+ and <seealso marker="config"><c>config(4)</c></seealso>):</p>
<code type="none">
{global_groups, [GroupTuple :: group_tuple()]}</code>
<p>For the processes and nodes to run smoothly using the global
@@ -54,22 +54,24 @@
</item>
<item>
<p>All involved nodes must agree on the global group definition,
- or the behavior of the system is undefined.</p>
+ otherwise the behavior of the system is undefined.</p>
</item>
<item>
- <p><em>All</em> nodes in the system should belong to exactly
+ <p><em>All</em> nodes in the system must belong to exactly
one global group.</p>
</item>
</list>
- <p>In the following description, a <em>group node</em> is a node
+ <p>In the following descriptions, a <em>group node</em> is a node
belonging to the same global group as the local node.</p>
</description>
- <datatypes>
+
+ <datatypes>
<datatype>
<name name="group_tuple"/>
<desc>
<p>A <c>GroupTuple</c> without <c>PublishType</c> is the same as a
- <c>GroupTuple</c> with <c>PublishType == normal</c>.</p>
+ <c>GroupTuple</c> with <c>PublishType</c> equal to <c>normal</c>.
+ </p>
</desc>
</datatype>
<datatype>
@@ -78,52 +80,57 @@
<datatype>
<name name="publish_type"/>
<desc>
- <p>A node started with the command line flag <c>-hidden</c>, see
- <seealso marker="erts:erl">erl(1)</seealso>, is said to be a
- <em>hidden</em> node. A hidden node will establish hidden
+ <p>A node started with command-line flag <c>-hidden</c> (see
+ <seealso marker="erts:erl"><c>erl(1)</c></seealso>) is said
+ to be a <em>hidden</em> 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.</p>
- <p>A global group defined with <c>PublishType == hidden</c>, 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 <c>-hidden</c> command line flag or not.</p>
+ <p>A global group defined with <c>PublishType</c> equal to
+ <c>hidden</c> 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 <c>-hidden</c> or not.</p>
</desc>
</datatype>
<datatype>
<name name="name"/>
<desc><p>A registered name.</p></desc>
</datatype>
+
<datatype>
<name name="where"/>
</datatype>
</datatypes>
+
<funcs>
<func>
<name name="global_groups" arity="0"/>
- <fsummary>Return the global group names</fsummary>
+ <fsummary>Return the global group names.</fsummary>
<desc>
- <p>Returns a tuple containing the name of the global group
+ <p>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 <c>undefined</c> if no global groups are
defined.</p>
</desc>
</func>
+
<func>
<name name="info" arity="0"/>
- <fsummary>Information about global groups</fsummary>
+ <fsummary>Information about global groups.</fsummary>
<type name="info_item"/>
<type name="sync_state"/>
<desc>
<p>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.</p>
+ groups. Each list element is a tuple. The order of
+ the tuples is undefined.</p>
<taglist>
<tag><c>{state, <anno>State</anno>}</c></tag>
<item>
<p>If the local node is part of a global group,
- <c><anno>State</anno> == synced</c>. If no global groups are defined,
- <c><anno>State</anno> == no_conf</c>.</p>
+ <c><anno>State</anno></c> is equal to <c>synced</c>.
+ If no global groups are defined,
+ <c><anno>State</anno></c> is equal to <c>no_conf</c>.</p>
</item>
<tag><c>{own_group_name, <anno>GroupName</anno>}</c></tag>
<item>
@@ -152,117 +159,131 @@
<tag><c>{other_groups, <anno>Groups</anno>}</c></tag>
<item>
<p><c><anno>Groups</anno></c> is a list of tuples
- <c>{<anno>GroupName</anno>, <anno>Nodes</anno>}</c>, specifying the name and nodes
+ <c>{<anno>GroupName</anno>, <anno>Nodes</anno>}</c>,
+ specifying the name and nodes
of the other global groups.</p>
</item>
<tag><c>{monitoring, <anno>Pids</anno>}</c></tag>
<item>
- <p>A list of pids, specifying the processes which have
+ <p>A list of pids, specifying the processes that have
subscribed to <c>nodeup</c> and <c>nodedown</c> messages.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="monitor_nodes" arity="1"/>
- <fsummary>Subscribe to node status changes</fsummary>
+ <fsummary>Subscribe to node status changes.</fsummary>
<desc>
- <p>Depending on <c><anno>Flag</anno></c>, the calling process starts
- subscribing (<c><anno>Flag</anno> == true</c>) or stops subscribing
- (<c><anno>Flag</anno> == false</c>) to node status change messages.</p>
- <p>A process which has subscribed will receive the messages
+ <p>Depending on <c><anno>Flag</anno></c>, the calling process
+ starts subscribing (<c><anno>Flag</anno></c> equal to
+ <c>true</c>) or stops subscribing (<c><anno>Flag</anno></c>
+ equal to <c>false</c>) to node status change messages.</p>
+ <p>A process that has subscribed receives the messages
<c>{nodeup, Node}</c> and <c>{nodedown, Node}</c> when a
group node connects or disconnects, respectively.</p>
</desc>
</func>
+
<func>
<name name="own_nodes" arity="0"/>
- <fsummary>Return the group nodes</fsummary>
+ <fsummary>Return the group nodes.</fsummary>
<desc>
<p>Returns the names of all group nodes, regardless of their
current status.</p>
</desc>
</func>
+
<func>
<name name="registered_names" arity="1"/>
- <fsummary>Return globally registered names</fsummary>
+ <fsummary>Return globally registered names.</fsummary>
<desc>
- <p>Returns a list of all names which are globally registered
+ <p>Returns a list of all names that are globally registered
on the specified node or in the specified global group.</p>
</desc>
</func>
+
<func>
<name name="send" arity="2"/>
<name name="send" arity="3"/>
- <fsummary>Send a message to a globally registered pid</fsummary>
+ <fsummary>Send a message to a globally registered pid.</fsummary>
<desc>
<p>Searches for <c><anno>Name</anno></c>, globally registered on
- the specified node or in the specified global group, or --
- if the <c><anno>Where</anno></c> 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 <c>global_groups</c>
- configuration parameter.</p>
- <p>If <c><anno>Name</anno></c> is found, the message <c><anno>Msg</anno></c> is sent to
+ the specified node or in the specified global group, or
+ (if argument <c><anno>Where</anno></c> is not provided) in any
+ global group. The global groups are searched in the order that
+ they appear in the value of configuration parameter
+ <c>global_groups</c>.</p>
+ <p>If <c><anno>Name</anno></c> is found, message
+ <c><anno>Msg</anno></c> 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
<c>{badarg, {<anno>Name</anno>, <anno>Msg</anno>}}</c>.</p>
</desc>
</func>
+
<func>
<name name="sync" arity="0"/>
- <fsummary>Synchronize the group nodes</fsummary>
+ <fsummary>Synchronize the group nodes.</fsummary>
<desc>
<p>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.</p>
<p>If synchronization is not possible, an error report is sent
- to the error logger (see also <c>error_logger(3)</c>).</p>
- <p>Failure:
- <c>{error, {'invalid global_groups definition', Bad}}</c> if
- the <c>global_groups</c> configuration parameter has an
+ to the error logger (see also
+ <seealso marker="error_logger"><c>error_logger(3)</c></seealso>.
+ </p>
+ <p>Returns <c>{error, {'invalid global_groups definition', Bad}}</c>
+ if configuration parameter <c>global_groups</c> has an
invalid value <c>Bad</c>.</p>
</desc>
</func>
+
<func>
<name name="whereis_name" arity="1"/>
<name name="whereis_name" arity="2"/>
- <fsummary>Get the pid with a given globally registered name</fsummary>
+ <fsummary>Get the pid with a specified globally registered name.</fsummary>
<desc>
<p>Searches for <c><anno>Name</anno></c>, globally registered on
- the specified node or in the specified global group, or -- if
- the <c><anno>Where</anno></c> 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 <c>global_groups</c>
- configuration parameter.</p>
- <p>If <c><anno>Name</anno></c> 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 <c><anno>Where</anno></c> is not provided) in any global
+ group. The global groups are searched in the order that
+ they appear in the value of configuration parameter
+ <c>global_groups</c>.</p>
+ <p>If <c><anno>Name</anno></c> is found, the corresponding pid is
+ returned. If the name is not found, the function returns
<c>undefined</c>.</p>
</desc>
</func>
</funcs>
<section>
- <title>NOTE</title>
- <p>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.</p>
- <p>Note also that the <c>send/2,3</c> function is not secure.</p>
- <p>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.</p>
+ <title>Notes</title>
+ <list type="bulleted">
+ <item><p>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.</p></item>
+ <item><p>Function
+ <seealso marker="#send/2"><c>send/2,3</c></seealso>
+ is not secure.</p></item>
+ <item><p>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.</p></item>
+ </list>
</section>
<section>
- <title>SEE ALSO</title>
- <p><seealso marker="erts:erl">erl(1)</seealso>,
- <seealso marker="global">global(3)</seealso></p>
+ <title>See Also</title>
+ <p><seealso marker="global"><c>global(3)</c></seealso>,
+ <seealso marker="erts:erl"><c>erl(1)</c></seealso></p>
</section>
</erlref>