aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/global_group.xml
diff options
context:
space:
mode:
authorErlang/OTP <otp@erlang.org>2009-11-20 14:54:40 +0000
committerErlang/OTP <otp@erlang.org>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/kernel/doc/src/global_group.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/kernel/doc/src/global_group.xml')
-rw-r--r--lib/kernel/doc/src/global_group.xml284
1 files changed, 284 insertions, 0 deletions
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1998</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+
+ </legalnotice>
+
+ <title>global_group</title>
+ <prepared>Esko Vierum&auml;ki</prepared>
+ <docno></docno>
+ <date>1998-12-18</date>
+ <rev>b</rev>
+ </header>
+ <module>global_group</module>
+ <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
+ 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>
+ <code type="none">
+{global_groups, [GroupTuple]}</code>
+ <p>Types:</p>
+ <list type="bulleted">
+ <item><c>GroupTuple = {GroupName, [Node]} | {GroupName, PublishType, [Node]}</c></item>
+ <item><c>GroupName = atom()</c> (naming a global group)</item>
+ <item><c>PublishType = normal | hidden</c></item>
+ <item><c>Node = atom()</c> (naming a node)</item>
+ </list>
+ <p>A <c>GroupTuple</c> without <c>PublishType</c> is the same as a
+ <c>GroupTuple</c> with <c>PublishType == normal</c>.</p>
+ <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
+ 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>For the processes and nodes to run smoothly using the global
+ group functionality, the following criteria must be met:</p>
+ <list type="bulleted">
+ <item>
+ <p>An instance of the global group server, <c>global_group</c>,
+ must be running on each node. The processes are automatically
+ started and synchronized when a node is started.</p>
+ </item>
+ <item>
+ <p>All involved nodes must agree on the global group definition,
+ or the behavior of the system is undefined.</p>
+ </item>
+ <item>
+ <p><em>All</em> nodes in the system should belong to exactly
+ one global group.</p>
+ </item>
+ </list>
+ <p>In the following description, a <em>group node</em> is a node
+ belonging to the same global group as the local node.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>global_groups() -> {GroupName, GroupNames} | undefined</name>
+ <fsummary>Return the global group names</fsummary>
+ <type>
+ <v>GroupName = atom()</v>
+ <v>GroupNames = [GroupName]</v>
+ </type>
+ <desc>
+ <p>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 <c>undefined</c> if no global groups are
+ defined.</p>
+ </desc>
+ </func>
+ <func>
+ <name>info() -> [{Item, Info}]</name>
+ <fsummary>Information about global groups</fsummary>
+ <type>
+ <v>Item, Info -- see below</v>
+ </type>
+ <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>
+ <taglist>
+ <tag><c>{state, State}</c></tag>
+ <item>
+ <p>If the local node is part of a global group,
+ <c>State == synced</c>. If no global groups are defined,
+ <c>State == no_conf</c>.</p>
+ </item>
+ <tag><c>{own_group_name, GroupName}</c></tag>
+ <item>
+ <p>The name (atom) of the group that the local node belongs
+ to.</p>
+ </item>
+ <tag><c>{own_group_nodes, Nodes}</c></tag>
+ <item>
+ <p>A list of node names (atoms), the group nodes.</p>
+ </item>
+ <tag><c>{synced_nodes, Nodes}</c></tag>
+ <item>
+ <p>A list of node names, the group nodes currently
+ synchronized with the local node.</p>
+ </item>
+ <tag><c>{sync_error, Nodes}</c></tag>
+ <item>
+ <p>A list of node names, the group nodes with which
+ the local node has failed to synchronize.</p>
+ </item>
+ <tag><c>{no_contact, Nodes}</c></tag>
+ <item>
+ <p>A list of node names, the group nodes to which there are
+ currently no connections.</p>
+ </item>
+ <tag><c>{other_groups, Groups}</c></tag>
+ <item>
+ <p><c>Groups</c> is a list of tuples
+ <c>{GroupName, Nodes}</c>, specifying the name and nodes
+ of the other global groups.</p>
+ </item>
+ <tag><c>{monitoring, Pids}</c></tag>
+ <item>
+ <p>A list of pids, specifying the processes which have
+ subscribed to <c>nodeup</c> and <c>nodedown</c> messages.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>monitor_nodes(Flag) -> ok </name>
+ <fsummary>Subscribe to node status changes</fsummary>
+ <type>
+ <v>Flag = bool()</v>
+ </type>
+ <desc>
+ <p>Depending on <c>Flag</c>, the calling process starts
+ subscribing (<c>Flag == true</c>) or stops subscribing
+ (<c>Flag == false</c>) to node status change messages.</p>
+ <p>A process which has subscribed will receive the messages
+ <c>{nodeup, Node}</c> and <c>{nodedown, Node}</c> when a
+ group node connects or disconnects, respectively.</p>
+ </desc>
+ </func>
+ <func>
+ <name>own_nodes() -> Nodes</name>
+ <fsummary>Return the group nodes</fsummary>
+ <type>
+ <v>Nodes = [Node]</v>
+ <v>&nbsp;Node = node()</v>
+ </type>
+ <desc>
+ <p>Returns the names of all group nodes, regardless of their
+ current status.</p>
+ </desc>
+ </func>
+ <func>
+ <name>registered_names(Where) -> Names</name>
+ <fsummary>Return globally registered names</fsummary>
+ <type>
+ <v>Where = {node, Node} | {group, GroupName}</v>
+ <v>&nbsp;Node = node()</v>
+ <v>&nbsp;GroupName = atom()</v>
+ <v>Names = [Name]</v>
+ <v>&nbsp;Name = atom()</v>
+ </type>
+ <desc>
+ <p>Returns a list of all names which are globally registered
+ on the specified node or in the specified global group.</p>
+ </desc>
+ </func>
+ <func>
+ <name>send(Name, Msg) -> pid() | {badarg, {Name, Msg}}</name>
+ <name>send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}</name>
+ <fsummary>Send a message to a globally registered pid</fsummary>
+ <type>
+ <v>Where = {node, Node} | {group, GroupName}</v>
+ <v>&nbsp;Node = node()</v>
+ <v>&nbsp;GroupName = atom()</v>
+ <v>Name = atom()</v>
+ <v>Msg = term()</v>
+ </type>
+ <desc>
+ <p>Searches for <c>Name</c>, globally registered on
+ the specified node or in the specified global group, or --
+ if the <c>Where</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>Name</c> is found, the message <c>Msg</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, {Name, Msg}}</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>sync() -> ok</name>
+ <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
+ 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
+ invalid value <c>Bad</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>whereis_name(Name) -> pid() | undefined</name>
+ <name>whereis_name(Where, Name) -> pid() | undefined</name>
+ <fsummary>Get the pid with a given globally registered name</fsummary>
+ <type>
+ <v>Where = {node, Node} | {group, GroupName}</v>
+ <v>&nbsp;Node = node()</v>
+ <v>&nbsp;GroupName = atom()</v>
+ <v>Name = atom()</v>
+ </type>
+ <desc>
+ <p>Searches for <c>Name</c>, globally registered on
+ the specified node or in the specified global group, or -- if
+ the <c>Where</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>Name</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>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p><seealso marker="erts:erl">erl(1)</seealso>,
+ <seealso marker="global">global(3)</seealso></p>
+ </section>
+</erlref>
+