diff options
Diffstat (limited to 'lib/kernel/doc/src/global_group.xml')
| -rw-r--r-- | lib/kernel/doc/src/global_group.xml | 175 |
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ä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> |