File 0965-Document-noconnection-error-more-prominently.patch of Package erlang
From 986fc617e2f9fc2e2eb174050edd4f3d450d2992 Mon Sep 17 00:00:00 2001
From: Adam Lindberg <hello@alind.io>
Date: Tue, 17 Dec 2019 18:00:21 +0100
Subject: [PATCH] Document noconnection error more prominently
---
erts/doc/src/erlang.xml | 47 +++++++++++++++++++++-------------
system/doc/reference_manual/errors.xml | 6 ++++-
2 files changed, 34 insertions(+), 19 deletions(-)
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 7094d67cb0..90ef9d8584 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2423,26 +2423,37 @@ false</code>
<name name="link" arity="1"/>
<fsummary>Create a link to another process (or port).</fsummary>
<desc>
- <p>Creates a link between the calling process and another
- process (or port) <c><anno>PidOrPort</anno></c>, if there is
- not such a link
- already. If a process attempts to create a link to itself,
- nothing is done. Returns <c>true</c>.</p>
- <p>If <c><anno>PidOrPort</anno></c> does not exist, the behavior
- of the BIF
- depends on if the calling process is trapping exits or not (see
- <seealso marker="#process_flag/2">
- <c>process_flag/2</c></seealso>):</p>
+
+ <p>Creates a link between the calling process and another process (or
+ port) <c><anno>PidOrPort</anno></c>. If the link already exists or a
+ process attempts to create a link to itself, nothing is done. Returns
+ <c>true</c> if the link is set up.</p>
+
+ <p>If <c><anno>PidOrPort</anno></c> does not exist and checking it is
+ cheap, a <c>noproc</c> error is raised. Currently, checking is cheap
+ if the <c><anno>PidOrPort</anno></c> is local and the caller does not
+ trap exits (see <seealso marker="#process_flag/2"><c>process_flag/2
+ </c></seealso>).</p>
+
+ <p>Apart from any exit signals from the linked process itself, two
+ special exit signals may be sent to the calling process:</p>
+
<list type="bulleted">
- <item><p>If the calling process is not trapping exits, and
- checking <c><anno>PidOrPort</anno></c> is cheap
- (that is, if <c><anno>PidOrPort</anno></c>
- is local), <c>link/1</c> fails with reason <c>noproc</c>.</p></item>
- <item><p>Otherwise, if the calling process is trapping exits,
- and/or <c><anno>PidOrPort</anno></c> is remote, <c>link/1</c>
- returns <c>true</c>, but an exit signal with reason <c>noproc</c>
- is sent to the calling process.</p></item>
+
+ <item><p><c>noproc</c> is sent immediately if
+ <c><anno>PidOrPort</anno></c> does not exist at the time of linking
+ (if the caller is trapping exits or <c><anno>PidOrPort</anno></c> is
+ remote).</p></item>
+
+ <item><p><c>noconnection</c> if <c><anno>PidOrPort</anno></c> is
+ remote and a connection between the nodes could not be established
+ or was severed.</p></item>
+
</list>
+
+ <p>See <seealso marker="doc/reference_manual:processes#links">Processes
+ ➜ Links</seealso> in the Erlang Reference Manual for more details.</p>
+
</desc>
</func>
diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml
index 16d3e7590e..f692015729 100644
--- a/system/doc/reference_manual/errors.xml
+++ b/system/doc/reference_manual/errors.xml
@@ -237,7 +237,11 @@
</row>
<row>
<cell align="left" valign="middle"><c>noproc</c></cell>
- <cell align="left" valign="middle">Trying to link to a non-existing process.</cell>
+ <cell align="left" valign="middle">Trying to link or monitor to a non-existing process or port.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>noconnection</c></cell>
+ <cell align="left" valign="middle">A link or monitor to a remote process was broken because a connection between the nodes could not be established or was severed.</cell>
</row>
<row>
<cell align="left" valign="middle"><c>{nocatch,V}</c></cell>
--
2.16.4
