aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/net_kernel.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/net_kernel.xml')
-rw-r--r--lib/kernel/doc/src/net_kernel.xml277
1 files changed, 143 insertions, 134 deletions
diff --git a/lib/kernel/doc/src/net_kernel.xml b/lib/kernel/doc/src/net_kernel.xml
index 311e0d8ea4..2d52adc2eb 100644
--- a/lib/kernel/doc/src/net_kernel.xml
+++ b/lib/kernel/doc/src/net_kernel.xml
@@ -25,41 +25,47 @@
<title>net_kernel</title>
<prepared>Claes Wikstrom</prepared>
<docno>1</docno>
- <date>96-09-10</date>
+ <date>1996-09-10</date>
<rev>A</rev>
</header>
<module>net_kernel</module>
- <modulesummary>Erlang Networking Kernel</modulesummary>
+ <modulesummary>Erlang networking kernel.</modulesummary>
<description>
<p>The net kernel is a system process, registered as
- <c>net_kernel</c>, which must be running for distributed Erlang
+ <c>net_kernel</c>, which must be operational for distributed Erlang
to work. The purpose of this process is to implement parts of
the BIFs <c>spawn/4</c> and <c>spawn_link/4</c>, and to provide
monitoring of the network.</p>
- <p>An Erlang node is started using the command line flag
+ <p>An Erlang node is started using command-line flag
<c>-name</c> or <c>-sname</c>:</p>
-<pre>$ <input>erl -sname foobar</input></pre>
+ <pre>
+$ <input>erl -sname foobar</input></pre>
<p>It is also possible to call <c>net_kernel:start([foobar])</c>
directly from the normal Erlang shell prompt:</p>
-<pre>1> <input>net_kernel:start([foobar, shortnames]).</input>
+ <pre>
+1> <input>net_kernel:start([foobar, shortnames]).</input>
{ok,&lt;0.64.0>}
(foobar@gringotts)2></pre>
- <p>If the node is started with the command line flag <c>-sname</c>,
- the node name will be <c>foobar@Host</c>, where <c>Host</c> is
+ <p>If the node is started with command-line flag <c>-sname</c>,
+ the node name is <c>foobar@Host</c>, where <c>Host</c> is
the short name of the host (not the fully qualified domain name).
- If started with the <c>-name</c> flag, <c>Host</c> is the fully
- qualified domain name. See <c>erl(1)</c>.</p>
+ If started with flag <c>-name</c>, the node name is <c>foobar@Host</c>,
+ where <c>Host</c> is the fully qualified domain name.
+ For more information, see
+ <seealso marker="erts:erl"><c>erl</c></seealso>.</p>
<p>Normally, connections are established automatically when
another node is referenced. This functionality can be disabled
- by setting the Kernel configuration parameter
+ by setting <c>Kernel</c> configuration parameter
<c>dist_auto_connect</c> to <c>false</c>, see
- <seealso marker="kernel_app">kernel(6)</seealso>. In this case,
+ <seealso marker="kernel_app"><c>kernel(6)</c></seealso>. In this case,
connections must be established explicitly by calling
- <c>net_kernel:connect_node/1</c>.</p>
- <p>Which nodes are allowed to communicate with each other is handled
- by the magic cookie system, see
- <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> in the Erlang Reference Manual.</p>
+ <seealso marker="#connect_node/1"><c>connect_node/1</c></seealso>.</p>
+ <p>Which nodes that are allowed to communicate with each other is handled
+ by the magic cookie system, see section
+ <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso>
+ in the Erlang Reference Manual.</p>
</description>
+
<funcs>
<func>
<name name="allow" arity="1"/>
@@ -77,237 +83,240 @@
an atom.</p>
</desc>
</func>
+
<func>
<name name="connect_node" arity="1"/>
- <fsummary>Establish a connection to a node</fsummary>
+ <fsummary>Establish a connection to a node.</fsummary>
<desc>
- <p>Establishes a connection to <c><anno>Node</anno></c>. Returns <c>true</c>
- if successful, <c>false</c> if not, and <c>ignored</c> if
- the local node is not alive.</p>
+ <p>Establishes a connection to <c><anno>Node</anno></c>. Returns
+ <c>true</c> if successful, <c>false</c> if not, and <c>ignored</c>
+ if the local node is not alive.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_net_ticktime" arity="0"/>
+ <fsummary>Get <c>net_ticktime</c>.</fsummary>
+ <desc>
+ <p>Gets <c>net_ticktime</c> (see
+ <seealso marker="kernel_app"><c>kernel(6)</c></seealso>).</p>
+ <p>Defined return values (<c><anno>Res</anno></c>):</p>
+ <taglist>
+ <tag><c><anno>NetTicktime</anno></c></tag>
+ <item><p><c>net_ticktime</c> is <c><anno>NetTicktime</anno></c>
+ seconds.</p></item>
+ <tag><c>{ongoing_change_to, <anno>NetTicktime</anno>}</c></tag>
+ <item><p><c>net_kernel</c> is currently changing
+ <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c>
+ seconds.</p></item>
+ <tag><c>ignored</c></tag>
+ <item><p>The local node is not alive.</p></item>
+ </taglist>
</desc>
</func>
+
<func>
<name name="monitor_nodes" arity="1"/>
<name name="monitor_nodes" arity="2"/>
- <fsummary>Subscribe to node status change messages</fsummary>
+ <fsummary>Subscribe to node status change messages.</fsummary>
<desc>
<p>The calling process subscribes or unsubscribes to node
status change messages. A <c>nodeup</c> message is delivered
- to all subscribing process when a new node is connected, and
+ to all subscribing processes when a new node is connected, and
a <c>nodedown</c> message is delivered when a node is
disconnected.</p>
- <p>If <c><anno>Flag</anno></c> is <c>true</c>, a new subscription is started.
- If <c><anno>Flag</anno></c> is <c>false</c>, all previous subscriptions --
- started with the same <c><anno>Options</anno></c> -- are stopped. Two
+ <p>If <c><anno>Flag</anno></c> is <c>true</c>, a new subscription is
+ started. If <c><anno>Flag</anno></c> is <c>false</c>, all previous
+ subscriptions started with the same <c><anno>Options</anno></c>
+ are stopped. Two
option lists are considered the same if they contain the same
set of options.</p>
- <p>As of <c>kernel</c> version 2.11.4, and <c>erts</c> version
+ <p>As from <c>Kernel</c> version 2.11.4, and <c>ERTS</c> version
5.5.4, the following is guaranteed:</p>
<list type="bulleted">
- <item><c>nodeup</c> messages will be delivered before delivery
- of any message from the remote node passed through the
- newly established connection.</item>
- <item><c>nodedown</c> messages will not be delivered until all
- messages from the remote node that have been passed
- through the connection have been delivered.</item>
+ <item><p><c>nodeup</c> messages are delivered before delivery
+ of any message from the remote node passed through the
+ newly established connection.</p></item>
+ <item><p><c>nodedown</c> messages are not delivered until all
+ messages from the remote node that have been passed
+ through the connection have been delivered.</p></item>
</list>
- <p>Note, that this is <em>not</em> guaranteed for <c>kernel</c>
+ <p>Notice that this is <em>not</em> guaranteed for <c>Kernel</c>
versions before 2.11.4.</p>
- <p>As of <c>kernel</c> version 2.11.4 subscriptions can also be
- made before the <c>net_kernel</c> server has been started,
- i.e., <c>net_kernel:monitor_nodes/[1,2]</c> does not return
+ <p>As from <c>Kernel</c> version 2.11.4, subscriptions can also be
+ made before the <c>net_kernel</c> server is started, that is,
+ <c>net_kernel:monitor_nodes/[1,2]</c> does not return
<c>ignored</c>.</p>
- <p>As of <c>kernel</c> version 2.13, and <c>erts</c> version
+ <p>As from <c>Kernel</c> version 2.13, and <c>ERTS</c> version
5.7, the following is guaranteed:</p>
<list type="bulleted">
- <item><c>nodeup</c> messages will be delivered after the
- corresponding node appears in results from
- <c>erlang:nodes/X</c>.</item>
- <item><c>nodedown</c> messages will be delivered after the
- corresponding node has disappeared in results from
- <c>erlang:nodes/X</c>.</item>
+ <item><p><c>nodeup</c> messages are delivered after the
+ corresponding node appears in results from
+ <c>erlang:nodes/X</c>.</p></item>
+ <item><p><c>nodedown</c> messages are delivered after the
+ corresponding node has disappeared in results from
+ <c>erlang:nodes/X</c>.</p></item>
</list>
- <p>Note, that this is <em>not</em> guaranteed for <c>kernel</c>
+ <p>Notice that this is <em>not</em> guaranteed for <c>Kernel</c>
versions before 2.13.</p>
<p>The format of the node status change messages depends on
- <c><anno>Options</anno></c>. If <c><anno>Options</anno></c> is [], which is the default,
- the format is:</p>
+ <c><anno>Options</anno></c>. If <c><anno>Options</anno></c> is
+ <c>[]</c>, which is the default, the format is as follows:</p>
<code type="none">
{nodeup, Node} | {nodedown, Node}
Node = node()</code>
- <p>If <c><anno>Options</anno> /= []</c>, the format is:</p>
+ <p>If <c><anno>Options</anno></c> is not <c>[]</c>, the format is
+ as follows:</p>
<code type="none">
{nodeup, Node, InfoList} | {nodedown, Node, InfoList}
Node = node()
InfoList = [{Tag, Val}]</code>
<p><c>InfoList</c> is a list of tuples. Its contents depends on
<c><anno>Options</anno></c>, see below.</p>
- <p>Also, when <c>OptionList == []</c> only visible nodes, that
+ <p>Also, when <c>OptionList == []</c>, only visible nodes, that
is, nodes that appear in the result of
- <seealso marker="erts:erlang#nodes/0">nodes/0</seealso>, are
- monitored.</p>
+ <seealso marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seealso>,
+ are monitored.</p>
<p><c><anno>Option</anno></c> can be any of the following:</p>
<taglist>
<tag><c>{node_type, NodeType}</c></tag>
<item>
- <p>Currently valid values for <c>NodeType</c> are:</p>
+ <p>Valid values for <c>NodeType</c>:</p>
<taglist>
<tag><c>visible</c></tag>
- <item>Subscribe to node status change messages for visible
+ <item><p>Subscribe to node status change messages for visible
nodes only. The tuple <c>{node_type, visible}</c> is
- included in <c>InfoList</c>.</item>
+ included in <c>InfoList</c>.</p></item>
<tag><c>hidden</c></tag>
- <item>Subscribe to node status change messages for hidden
+ <item><p>Subscribe to node status change messages for hidden
nodes only. The tuple <c>{node_type, hidden}</c> is
- included in <c>InfoList</c>.</item>
+ included in <c>InfoList</c>.</p></item>
<tag><c>all</c></tag>
- <item>Subscribe to node status change messages for both
+ <item><p>Subscribe to node status change messages for both
visible and hidden nodes. The tuple
- <c>{node_type, visible | hidden}</c> is included in
- <c>InfoList</c>.</item>
+ <c>{node_type, visible | hidden}</c> is included in
+ <c>InfoList</c>.</p></item>
</taglist>
</item>
<tag><c>nodedown_reason</c></tag>
<item>
<p>The tuple <c>{nodedown_reason, Reason}</c> is included in
- <c>InfoList</c> in <c>nodedown</c> messages. <c>Reason</c>
- can be:</p>
+ <c>InfoList</c> in <c>nodedown</c> messages.</p>
+ <p><c>Reason</c> can be any of the following:</p>
<taglist>
<tag><c>connection_setup_failed</c></tag>
- <item>The connection setup failed (after <c>nodeup</c>
- messages had been sent).</item>
+ <item><p>The connection setup failed (after <c>nodeup</c>
+ messages were sent).</p></item>
<tag><c>no_network</c></tag>
- <item>No network available.</item>
+ <item><p>No network is available.</p></item>
<tag><c>net_kernel_terminated</c></tag>
- <item>The <c>net_kernel</c> process terminated.</item>
+ <item><p>The <c>net_kernel</c> process terminated.</p></item>
<tag><c>shutdown</c></tag>
- <item>Unspecified connection shutdown.</item>
+ <item><p>Unspecified connection shutdown.</p></item>
<tag><c>connection_closed</c></tag>
- <item>The connection was closed.</item>
+ <item><p>The connection was closed.</p></item>
<tag><c>disconnect</c></tag>
- <item>The connection was disconnected (forced from the
- current node).</item>
+ <item><p>The connection was disconnected (forced from the
+ current node).</p></item>
<tag><c>net_tick_timeout</c></tag>
- <item>Net tick timeout.</item>
+ <item><p>Net tick time-out.</p></item>
<tag><c>send_net_tick_failed</c></tag>
- <item>Failed to send net tick over the connection.</item>
+ <item><p>Failed to send net tick over the connection.</p></item>
<tag><c>get_status_failed</c></tag>
- <item>Status information retrieval from the <c>Port</c>
- holding the connection failed.</item>
+ <item><p>Status information retrieval from the <c>Port</c>
+ holding the connection failed.</p></item>
</taglist>
</item>
</taglist>
</desc>
</func>
- <func>
- <name name="get_net_ticktime" arity="0"/>
- <fsummary>Get <c>net_ticktime</c></fsummary>
- <desc>
- <p>Gets <c>net_ticktime</c> (see
- <seealso marker="kernel_app">kernel(6)</seealso>).</p>
- <p>Currently defined return values (<c><anno>Res</anno></c>):</p>
- <taglist>
- <tag><c><anno>NetTicktime</anno></c></tag>
- <item>
- <p><c>net_ticktime</c> is <c><anno>NetTicktime</anno></c> seconds.</p>
- </item>
- <tag><c>{ongoing_change_to, <anno>NetTicktime</anno>}</c></tag>
- <item>
- <p><c>net_kernel</c> is currently changing
- <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c> seconds.</p>
- </item>
- <tag><c>ignored</c></tag>
- <item>
- <p>The local node is not alive.</p>
- </item>
- </taglist>
- </desc>
- </func>
+
<func>
<name name="set_net_ticktime" arity="1"/>
<name name="set_net_ticktime" arity="2"/>
- <fsummary>Set <c>net_ticktime</c></fsummary>
+ <fsummary>Set <c>net_ticktime</c>.</fsummary>
<desc>
<p>Sets <c>net_ticktime</c> (see
- <seealso marker="kernel_app">kernel(6)</seealso>) to
- <c><anno>NetTicktime</anno></c> seconds. <c><anno>TransitionPeriod</anno></c> defaults
- to 60.</p>
+ <seealso marker="kernel_app"><c>kernel(6)</c></seealso>) to
+ <c><anno>NetTicktime</anno></c> seconds.
+ <c><anno>TransitionPeriod</anno></c> defaults to <c>60</c>.</p>
<p>Some definitions:</p>
<taglist>
- <tag>The minimum transition traffic interval (<c>MTTI</c>)</tag>
- <item>
- <p><c>minimum(<anno>NetTicktime</anno>, PreviousNetTicktime)*1000 div 4</c> milliseconds.</p>
- </item>
- <tag>The transition period</tag>
- <item>
- <p>The time of the least number of consecutive <c>MTTI</c>s
- to cover <c><anno>TransitionPeriod</anno></c> seconds following
- the call to <c>set_net_ticktime/2</c> (i.e.
- ((<c><anno>TransitionPeriod</anno>*1000 - 1) div MTTI + 1)*MTTI</c>
- milliseconds).</p>
- </item>
+ <tag>Minimum transition traffic interval (<c>MTTI</c>)</tag>
+ <item><p><c>minimum(<anno>NetTicktime</anno>,
+ PreviousNetTicktime)*1000 div 4</c> milliseconds.</p></item>
+ <tag>Transition period</tag>
+ <item><p>The time of the least number of consecutive <c>MTTI</c>s
+ to cover <c><anno>TransitionPeriod</anno></c> seconds following
+ the call to <c>set_net_ticktime/2</c> (that is,
+ ((<c><anno>TransitionPeriod</anno>*1000 - 1) div MTTI + 1)*MTTI</c>
+ milliseconds).</p></item>
</taglist>
- <p>If <c><![CDATA[<anno>NetTicktime</anno> < PreviousNetTicktime]]></c>, the actual
- <c>net_ticktime</c> change will be done at the end of
- the transition period; otherwise, at the beginning. During
- the transition period, <c>net_kernel</c> will ensure that
- there will be outgoing traffic on all connections at least
+ <p>If
+ <c><![CDATA[NetTicktime < PreviousNetTicktime]]></c>,
+ the <c>net_ticktime</c> change is done at the end of
+ the transition period; otherwise at the beginning. During
+ the transition period, <c>net_kernel</c> ensures that
+ there is outgoing traffic on all connections at least
every <c>MTTI</c> millisecond.</p>
<note>
- <p>The <c>net_ticktime</c> changes have to be initiated on all
+ <p>The <c>net_ticktime</c> changes must be initiated on all
nodes in the network (with the same <c><anno>NetTicktime</anno></c>)
before the end of any transition period on any node;
- otherwise, connections may erroneously be disconnected.</p>
+ otherwise connections can erroneously be disconnected.</p>
</note>
<p>Returns one of the following:</p>
<taglist>
<tag><c>unchanged</c></tag>
<item>
- <p><c>net_ticktime</c> already had the value of
- <c><anno>NetTicktime</anno></c> and was left unchanged.</p>
+ <p><c>net_ticktime</c> already has the value of
+ <c><anno>NetTicktime</anno></c> and is left unchanged.</p>
</item>
<tag><c>change_initiated</c></tag>
<item>
- <p><c>net_kernel</c> has initiated the change of
- <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c> seconds.</p>
+ <p><c>net_kernel</c> initiated the change of
+ <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c>
+ seconds.</p>
</item>
<tag><c>{ongoing_change_to, <anno>NewNetTicktime</anno>}</c></tag>
<item>
- <p>The request was <em>ignored</em>; because,
- <c>net_kernel</c> was busy changing <c>net_ticktime</c> to
+ <p>The request is <em>ignored</em> because
+ <c>net_kernel</c> is busy changing <c>net_ticktime</c> to
<c><anno>NewNetTicktime</anno></c> seconds.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name>start([Name]) -> {ok, pid()} | {error, Reason}</name>
<name>start([Name, NameType]) -> {ok, pid()} | {error, Reason}</name>
<name>start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}</name>
- <fsummary>Turn an Erlang runtime system into a distributed node</fsummary>
+ <fsummary>Turn an Erlang runtime system into a distributed node.</fsummary>
<type>
<v>Name = atom()</v>
<v>NameType = shortnames | longnames</v>
<v>Reason = {already_started, pid()} | term()</v>
</type>
<desc>
- <p>Note that the argument is a list with exactly one, two or
- three arguments. <c>NameType</c> defaults to <c>longnames</c>
- and <c>Ticktime</c> to 15000.</p>
<p>Turns a non-distributed node into a distributed node by
starting <c>net_kernel</c> and other necessary processes.</p>
+ <p>Notice that the argument is a list with exactly one, two, or
+ three arguments. <c>NameType</c> defaults to <c>longnames</c>
+ and <c>Ticktime</c> to <c>15000</c>.</p>
</desc>
</func>
+
<func>
<name name="stop" arity="0"/>
- <fsummary>Turn a node into a non-distributed Erlang runtime system</fsummary>
+ <fsummary>Turn a node into a non-distributed Erlang runtime system.</fsummary>
<desc>
<p>Turns a distributed node into a non-distributed node. For
other nodes in the network, this is the same as the node
- going down. Only possible when the net kernel was started
- using <c>start/1</c>, otherwise returns
- <c>{error, not_allowed}</c>. Returns <c>{error, not_found}</c>
- if the local node is not alive.</p>
+ going down. Only possible when the net kernel was started using
+ <seealso marker="#start/1"><c>start/1</c></seealso>,
+ otherwise <c>{error, not_allowed}</c> is returned. Returns
+ <c>{error, not_found}</c> if the local node is not alive.</p>
</desc>
</func>
</funcs>