File 3675-erts-Add-documentation-about-name-service.patch of Package erlang
From 7cb19b8cb9fce5960fa56ef75c67610c2e89af41 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Tue, 18 May 2021 16:49:58 +0200
Subject: [PATCH 5/6] erts: Add documentation about name service
---
erts/doc/src/erlang.xml | 31 ++++++++++++++++------
system/doc/reference_manual/processes.xml | 32 +++++++++++++++++------
2 files changed, 47 insertions(+), 16 deletions(-)
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 85c80dfef2..08499ccd22 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -6623,14 +6623,21 @@ end</pre>
<name name="register" arity="2" since=""/>
<fsummary>Register a name for a pid (or port).</fsummary>
<desc>
- <p>Associates the name <c><anno>RegName</anno></c> with a process
- identifier (pid) or a port identifier.
+ <p>Registers the name <c><anno>RegName</anno></c> with a process
+ identifier (pid) or a port identifier in the
+ <seeguide marker="system/reference_manual:processes#runtime-service">
+ <c>name registry</c></seeguide>.
<c><anno>RegName</anno></c>, which must be an atom, can be used
instead of the pid or port identifier in send operator
- (<c><anno>RegName</anno> ! Message</c>). Example:</p>
+ (<c><anno>RegName</anno> ! Message</c>) and most other BIFs that
+ take a pid or port identifies as an argument. Example:</p>
<pre>
> <input>register(db, Pid).</input>
true</pre>
+ <p>The registered name is considered a
+ <seeguide marker="system/reference_manual:processes#visible-resources">
+ Directly Visible Erlang Resource</seeguide> and is automatically
+ unregistered when the process terminates.</p>
<p>Failures:</p>
<taglist>
<tag><c>badarg</c></tag>
@@ -12815,12 +12822,17 @@ end</code>
<name name="unregister" arity="1" since=""/>
<fsummary>Remove the registered name for a process (or port).</fsummary>
<desc>
- <p>Removes the registered name <c><anno>RegName</anno></c>
- associated with a
- process identifier or a port identifier, for example:</p>
+ <p>Removes the <seemfa marker="#register/2"><c>registered name</c></seemfa>
+ <c><anno>RegName</anno></c> associated with a
+ process identifier or a port identifier from the
+ <seeguide marker="system/reference_manual:processes#runtime-service">
+ <c>name registry</c></seeguide>. For example:</p>
<pre>
> <input>unregister(db).</input>
true</pre>
+ <p>Keep in mind that you can still receive signals associated with the
+ registered name after it has been unregistered as the sender may
+ have looked up the name before sending to it.</p>
<p>Users are advised not to unregister system processes.</p>
<p>Failure: <c>badarg</c> if <c>RegName</c> is not a registered
name.</p>
@@ -12833,8 +12845,11 @@ true</pre>
</fsummary>
<desc>
<p>Returns the process identifier or port identifier with
- the registered name <c>RegName</c>. Returns <c>undefined</c>
- if the name is not registered. Example:</p>
+ the <seemfa marker="#register/2"><c>registered name</c></seemfa>
+ <c>RegName</c> from the
+ <seeguide marker="system/reference_manual:processes#runtime-service">
+ <c>name registry</c></seeguide>.
+ Returns <c>undefined</c> if the name is not registered. Example:</p>
<pre>
> <input>whereis(db).</input>
<0.43.0></pre>
diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml
index 204cbf36fc..74ff2ba6e0 100644
--- a/system/doc/reference_manual/processes.xml
+++ b/system/doc/reference_manual/processes.xml
@@ -367,6 +367,22 @@ spawn(Module, Name, Args) -> pid()
responds with the reply signal.
</item>
+ <tag>
+ <c>register_name_request</c>/<c>register_name_reply</c>,
+ <c>unregister_name_request</c>/<c>unregister_name_reply</c>,
+ <c>whereis_name_request</c>/<c>whereis_name_reply</c>
+ </tag>
+ <item>
+ Sent due to a call to one of the
+ <seemfa marker="erts:erlang#register/2"><c>register/2</c></seemfa>,
+ <seemfa marker="erts:erlang#unregister/1"><c>unregister/1</c></seemfa>,
+ or
+ <seemfa marker="erts:erlang#whereis/1"><c>whereis/1</c></seemfa>
+ BIFs. The request signal is sent to the
+ <seeguide marker="#runtime-service">name service</seeguide> which
+ responds with the reply signal.
+ </item>
+
<tag>
<c>timer_start_request</c>/<c>timer_start_reply</c>,
<c>timer_cancel_request</c>/<c>timer_cancel_reply</c>
@@ -381,17 +397,17 @@ spawn(Module, Name, Args) -> pid()
<seeguide marker="#runtime-service">timer service</seeguide> which
responds with the reply signal.
</item>
-
+
</taglist>
<p><marker id="runtime-service"/>
- The clock service, the timer service, and the spawn service mentioned
- above are services provided by the runtime system. Each of these
- services consists of multiple independently executing entities. Such a
- service can be viewed as a group of processes, and could actually be
- implemented like that. Since each service consists of multiple
- independently executing entities, the order between multiple signals
- sent from one service to one process is <em>not</em> preserved. Note
+ The clock service, the name service, the timer service, and the spawn
+ service mentioned above are services provided by the runtime system.
+ Each of these services consists of multiple independently executing
+ entities. Such a service can be viewed as a group of processes, and
+ could actually be implemented like that. Since each service consists of
+ multiple independently executing entities, the order between multiple
+ signals sent from one service to one process is <em>not</em> preserved. Note
that this does <em>not</em> violate the
<seeguide marker="#signal-delivery">signal ordering
guarantee</seeguide> of the language.
--
2.26.2