diff options
Diffstat (limited to 'lib/kernel/doc/src/global_group.xml')
| -rw-r--r-- | lib/kernel/doc/src/global_group.xml | 284 |
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ä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> 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> Node = node()</v> + <v> GroupName = atom()</v> + <v>Names = [Name]</v> + <v> 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> Node = node()</v> + <v> 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> Node = node()</v> + <v> 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> + |