File 3675-erts-Add-documentation-about-name-service.... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

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>
 &lt;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

Places

File 3675-erts-Add-documentation-about-name-service.patch of Package erlang

Places