File 0894-erts-kernel-Rework-dynamic-node-name-doc.patch of Package erlang
From 1b00986a3588e809dc1c451d9726b640608dadd1 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Wed, 15 Dec 2021 19:53:06 +0100
Subject: [PATCH 1/2] erts,kernel: Rework dynamic node name doc
Move most of it from erl -name to new Dynamic Node Name section
under Distributed Erlang and mention it also under erl -sname
and net_kernel:start/1.
---
erts/doc/src/erl_cmd.xml | 34 ++++-------
lib/kernel/doc/src/net_kernel.xml | 9 ++-
system/doc/reference_manual/distributed.xml | 62 +++++++++++++++++++--
3 files changed, 76 insertions(+), 29 deletions(-)
diff --git a/erts/doc/src/erl_cmd.xml b/erts/doc/src/erl_cmd.xml
index c4a686b1f0..5803647d29 100644
--- a/erts/doc/src/erl_cmd.xml
+++ b/erts/doc/src/erl_cmd.xml
@@ -471,29 +471,11 @@ $ <input>erl \
instead.</p>
<p>If <c>Name</c> is set to <em><c>undefined</c></em> the node will
be started in a special mode optimized to be the temporary client
- of another node. When enabled the node will request a
- <seeguide marker="erl_dist_protocol#DFLAG_NAME_ME">dynamic
- node name</seeguide> from the first node it connects to. In addition
- these distribution settings will be set:
+ of another node. The node will then request a dynamic node
+ name from the first node it connects to. Read more in
+ <seeguide marker="system/reference_manual:distributed#dyn_node_name">
+ Dynamic Node Name</seeguide>.
</p>
- <pre><seeapp marker="kernel:kernel_app#dist_listen">-dist_listen false</seeapp> <seecom marker="#hidden">-hidden</seecom> <seeapp marker="kernel:kernel_app#dist_auto_connect">-dist_auto_connect never</seeapp></pre>
- <p>Because <c>-dist_auto_connect</c> is set to <c>never</c>, the system will have
- to manually call <seemfa marker="kernel:net_kernel#connect_node/1">
- <c>net_kernel:connect_node/1</c></seemfa> in order to start the distribution.
- If the distribution channel is closed, when a node uses a dynamic
- node name, the node will stop the distribution and a new call to
- <seemfa marker="kernel:net_kernel#connect_node/1">
- <c>net_kernel:connect_node/1</c></seemfa> has to be made. Note that the node
- name may change if the distribution is dropped and then set up again.
- </p>
- <note>
- <p>
- The <em>dynamic node name</em> feature is supported from
- OTP 23. Both the temporary client node and the first
- connected peer node (supplying the dynamic node name) must
- be at least OTP 23 for it to work.
- </p>
- </note>
<warning>
<p>
Starting a distributed node without also specifying
@@ -657,6 +639,14 @@ $ <input>erl \
exist between nodes running with flag <c><![CDATA[-sname]]></c>
and those running with flag <c><![CDATA[-name]]></c>, as node
names must be unique in distributed Erlang systems.</p>
+ <p>
+ If <c>Name</c> is set to <em><c>undefined</c></em> the node will
+ be started in a special mode optimized to be the temporary client
+ of another node. The node will then request a dynamic node
+ name from the first node it connects to. Read more in
+ <seeguide marker="system/reference_manual:distributed#dyn_node_name">
+ Dynamic Node Name</seeguide>.
+ </p>
<warning>
<p>
Starting a distributed node without also specifying
diff --git a/lib/kernel/doc/src/net_kernel.xml b/lib/kernel/doc/src/net_kernel.xml
index fd393df11c..c83793cc5b 100644
--- a/lib/kernel/doc/src/net_kernel.xml
+++ b/lib/kernel/doc/src/net_kernel.xml
@@ -359,6 +359,13 @@ $ <input>erl -sname foobar</input></pre>
starting <c>net_kernel</c> and other necessary processes.
</p>
+ <p>
+ If <c>Name</c> is set to <em><c>undefined</c></em> the distribution
+ will be started to request a dynamic node name from the first node it
+ connects to. See <seeguide marker="system/reference_manual:distributed#dyn_node_name">
+ Dynamic Node Name</seeguide>.
+ </p>
+
<p>Currently supported options:</p>
<taglist>
<tag><c>name_domain => <anno>NameDomain</anno></c></tag>
diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml
index 043f6e6734..cc4746825b 100644
--- a/system/doc/reference_manual/distributed.xml
+++ b/system/doc/reference_manual/distributed.xml
@@ -59,14 +59,18 @@
<section>
<title>Nodes</title>
- <p>A <em>node</em> is an executing Erlang runtime system that has
- been given a name, using the command-line flag <c>-name</c>
- (long names) or <c>-sname</c> (short names).</p>
+ <p>
+ A <em>node</em> is an executing Erlang runtime system that has
+ been given a name, using the command-line flag
+ <seecom marker="erts:erl#name"><c>-name</c></seecom> (long names) or
+ <seecom marker="erts:erl#sname"><c>-sname</c></seecom> (short names).
+ </p>
<p>The format of the node name is an atom <c>name@host</c>.
<c>name</c> is the name given by the user. <c>host</c> is
the full host name if long names are used, or the first part of
- the host name if short names are used. <c>node()</c> returns
- the name of the node.</p>
+ the host name if short names are used. Function
+ <seemfa marker="erts:erlang#node/0"><c>node()</c></seemfa>
+ returns the name of the node.</p>
<p><em>Example:</em></p>
<pre>
% <input>erl -name dilbert</input>
@@ -76,6 +80,21 @@
% <input>erl -sname dilbert</input>
(dilbert@uab)1> <input>node().</input>
dilbert@uab</pre>
+
+ <p>
+ The node name can also be given in runtime by calling
+ <seemfa marker="kernel:net_kernel#start/1"><c>net_kernel:start/1</c></seemfa>.
+ </p>
+ <p><em>Example:</em></p>
+ <pre>
+% <input>erl</input>
+1> <input>node().</input>
+nonode@nohost
+2> <input>net_kernel:start([dilbert,shortnames]).</input>
+{ok,<0.102.0>}
+(dilbert@uab)3> <input>node().</input>
+dilbert@uab</pre>
+
<note>
<p>A node with a long node name cannot communicate with a node
with a short node name.</p>
@@ -124,7 +143,38 @@ dilbert@uab</pre>
<c>nodes(connected)</c> must be used. This means, for example,
that the hidden node is not added to the set of nodes that
<c>global</c> is keeping track of.</p>
- <p>This feature was added in Erlang 5.0/OTP R7.</p>
+ </section>
+
+ <section>
+ <marker id="dyn_node_name"/>
+ <title>Dynamic Node Name</title>
+ <p>
+ If the node name is set to <em><c>undefined</c></em> the node will
+ be started in a special mode to be the temporary client
+ of another node. The node will then request a dynamic node
+ name from the first node it connects to. In addition these
+ distribution settings will be set:
+ </p>
+ <pre><seeapp marker="kernel:kernel_app#dist_listen">-dist_listen false</seeapp> <seecom marker="erts:erl#hidden">-hidden</seecom> <seeapp marker="kernel:kernel_app#dist_auto_connect">-dist_auto_connect never</seeapp></pre>
+ <p>
+ As <c>-dist_auto_connect</c> is set to <c>never</c>,
+ <seemfa marker="kernel:net_kernel#connect_node/1"><c>net_kernel:connect_node/1</c></seemfa>
+ must be called in order to setup connections. If the first established
+ connection is closed (which gave the node its dynamic name), then any
+ other connections will also be closed and the node will lose its dynamic
+ node name. A new call to
+ <seemfa marker="kernel:net_kernel#connect_node/1"><c>net_kernel:connect_node/1</c></seemfa>
+ can be made to get a new dynamic node name. The node name may
+ change if the distribution is dropped and then set up again.
+ </p>
+ <note>
+ <p>
+ The <em>dynamic node name</em> feature is supported from OTP 23.
+ Both the temporary client node and the first connected peer node
+ (supplying the dynamic node name) must be at least OTP 23 for it to
+ work.
+ </p>
+ </note>
</section>
<section>
--
2.34.1
