The R13B03 release.OTP_R13B03

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