aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/global_group.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2011-05-06 16:01:56 +0200
committerHans Bolinder <[email protected]>2011-05-11 14:20:58 +0200
commit5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 (patch)
treed77f79b9a1b98e7bf2bf3886ebec61d504317fc4 /lib/kernel/doc/src/global_group.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.gz
otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.bz2
otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.zip
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/kernel/doc/src/global_group.xml')
-rw-r--r--lib/kernel/doc/src/global_group.xml157
1 files changed, 70 insertions, 87 deletions
diff --git a/lib/kernel/doc/src/global_group.xml b/lib/kernel/doc/src/global_group.xml
index 4facf4a4aa..abf6178fc4 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>2009</year>
+ <year>1998</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -42,26 +42,7 @@
<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>
+{global_groups, [GroupTuple :: group_tuple()]}</code>
<p>For the processes and nodes to run smoothly using the global
group functionality, the following criteria must be met:</p>
<list type="bulleted">
@@ -82,14 +63,44 @@
<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>
+ <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>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="group_name"/>
+ </datatype>
+ <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
+ 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>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="name"/>
+ <desc><p>A registered name.</p></desc>
+ </datatype>
+ <datatype>
+ <name name="where"/>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>global_groups() -> {GroupName, GroupNames} | undefined</name>
+ <name name="global_groups" arity="0"/>
<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
@@ -98,53 +109,52 @@
</desc>
</func>
<func>
- <name>info() -> [{Item, Info}]</name>
+ <name name="info" arity="0"/>
<fsummary>Information about global groups</fsummary>
- <type>
- <v>Item, Info -- see below</v>
- </type>
+ <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>
<taglist>
- <tag><c>{state, State}</c></tag>
+ <tag><c>{state, <anno>State</anno>}</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>
+ <c><anno>State</anno> == synced</c>. If no global groups are defined,
+ <c><anno>State</anno> == no_conf</c>.</p>
</item>
- <tag><c>{own_group_name, GroupName}</c></tag>
+ <tag><c>{own_group_name, <anno>GroupName</anno>}</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>
+ <tag><c>{own_group_nodes, <anno>Nodes</anno>}</c></tag>
<item>
<p>A list of node names (atoms), the group nodes.</p>
</item>
- <tag><c>{synced_nodes, Nodes}</c></tag>
+ <tag><c>{synced_nodes, <anno>Nodes</anno>}</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>
+ <tag><c>{sync_error, <anno>Nodes</anno>}</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>
+ <tag><c>{no_contact, <anno>Nodes</anno>}</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>
+ <tag><c>{other_groups, <anno>Groups</anno>}</c></tag>
<item>
- <p><c>Groups</c> is a list of tuples
- <c>{GroupName, Nodes}</c>, specifying the name and nodes
+ <p><c><anno>Groups</anno></c> is a list of tuples
+ <c>{<anno>GroupName</anno>, <anno>Nodes</anno>}</c>, specifying the name and nodes
of the other global groups.</p>
</item>
- <tag><c>{monitoring, Pids}</c></tag>
+ <tag><c>{monitoring, <anno>Pids</anno>}</c></tag>
<item>
<p>A list of pids, specifying the processes which have
subscribed to <c>nodeup</c> and <c>nodedown</c> messages.</p>
@@ -153,73 +163,52 @@
</desc>
</func>
<func>
- <name>monitor_nodes(Flag) -> ok </name>
+ <name name="monitor_nodes" arity="1"/>
<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>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
<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>
+ <name name="own_nodes" arity="0"/>
<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>
+ <name name="registered_names" arity="1"/>
<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>
+ <name name="send" arity="2"/>
+ <name name="send" arity="3"/>
<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
+ <p>Searches for <c><anno>Name</anno></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
+ 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>Name</c> is found, the message <c>Msg</c> is sent to
+ <p>If <c><anno>Name</anno></c> is found, the 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, {Name, Msg}}</c>.</p>
+ <c>{badarg, {<anno>Name</anno>, <anno>Msg</anno>}}</c>.</p>
</desc>
</func>
<func>
- <name>sync() -> ok</name>
+ <name name="sync" arity="0"/>
<fsummary>Synchronize the group nodes</fsummary>
<desc>
<p>Synchronizes the group nodes, that is, the global name
@@ -235,23 +224,17 @@
</desc>
</func>
<func>
- <name>whereis_name(Name) -> pid() | undefined</name>
- <name>whereis_name(Where, Name) -> pid() | undefined</name>
+ <name name="whereis_name" arity="1"/>
+ <name name="whereis_name" arity="2"/>
<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
+ <p>Searches for <c><anno>Name</anno></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
+ 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>Name</c> is found, the corresponding pid is returned.
+ <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>