File 4543-erts-kernel-stdlib-Documentation-about-blocking-sign.patch of Package erlang
From 7417202cb4d0d606a2556920cb0e1292e433e5e2 Mon Sep 17 00:00:00 2001
From: Rickard Green <rickard@erlang.org>
Date: Fri, 24 Mar 2023 19:35:43 +0100
Subject: [PATCH 3/3] [erts,kernel,stdlib] Documentation about blocking
signaling
---
erts/doc/src/erlang.xml | 55 ++++++++++++++++++++++-
lib/kernel/doc/src/erpc.xml | 8 ++++
lib/kernel/doc/src/rpc.xml | 8 ++++
lib/stdlib/doc/src/gen_event.xml | 9 ++++
lib/stdlib/doc/src/gen_server.xml | 9 ++++
lib/stdlib/doc/src/gen_statem.xml | 8 ++++
system/doc/reference_manual/processes.xml | 47 ++++++++++++-------
7 files changed, 126 insertions(+), 18 deletions(-)
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 9b88331367..1c1749d7bf 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1677,6 +1677,12 @@ Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code>
<c>demonitor(<anno>MonitorRef</anno>, [flush])</c></seemfa>
can be used instead of <c>demonitor(<anno>MonitorRef</anno>)</c>
if this cleanup is wanted.</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
<change>
<p>Before Erlang/OTP R11B (ERTS 5.5) <c>demonitor/1</c>
behaved completely asynchronously, that is, the monitor was active
@@ -2284,6 +2290,12 @@ example_fun(A1, A2) ->
reasons.
</p>
</warning>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
</desc>
</func>
@@ -2926,6 +2938,12 @@ uncompiled code with the same arity are mapped to the same list by
and <seeguide marker="system/design_principles:applications#stopping">OTP
design principles</seeguide> related to starting and stopping
applications.</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
</desc>
</func>
@@ -3674,6 +3692,12 @@ is_process_alive(P2Pid),
chapter of the <i>ERTS User's Guide</i>.
</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
<p>Failure:</p>
<list>
<item><c>badarg</c> if <c><anno>PidOrPort</anno></c> does not identify
@@ -4684,6 +4708,12 @@ RealSystem = system + MissedSystem</code>
possible values for <c>Tag</c>, <c>Object</c>, and
<c>Info</c> in the monitor message will be introduced.</p>
</note>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
</desc>
</func>
@@ -7464,6 +7494,12 @@ true</pre>
<c><anno>Dest</anno></c> is an atom name, but this name is not
registered. This is the only case when <c>send</c> fails for an
unreachable destination <c><anno>Dest</anno></c> (of correct type).</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
</desc>
</func>
@@ -7491,6 +7527,12 @@ true</pre>
instead.
</item>
</taglist>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
<warning>
<p>As with <c>erlang:send_nosuspend/2,3</c>: use with extreme
care.</p>
@@ -8450,6 +8492,12 @@ true</pre>
A spawn request can be abandoned by calling
<seemfa marker="#spawn_request_abandon/1"><c>spawn_request_abandon/1</c></seemfa>.
</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
</desc>
</func>
@@ -13808,7 +13856,12 @@ end</code>
protocol</seeguide> can be found in the <i>Distribution Protocol</i>
chapter of the <i>ERTS User's Guide</i>.
</p>
-
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ </p></note>
<p>
Failure: <c>badarg</c> if <c>Id</c> does not identify a process
or a node local port.
diff --git a/lib/kernel/doc/src/erpc.xml b/lib/kernel/doc/src/erpc.xml
index 876a8a66b6..3f8664bae0 100644
--- a/lib/kernel/doc/src/erpc.xml
+++ b/lib/kernel/doc/src/erpc.xml
@@ -57,6 +57,14 @@
Note that it is up to the user to ensure that correct code to
execute via <c>erpc</c> is available on the involved nodes.
</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ Blocking Signaling Over Distribution</seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ Blocking signaling can, for example, cause timeouts in <c>erpc</c>
+ to be significantly delayed.
+ </p></note>
</description>
<datatypes>
diff --git a/lib/kernel/doc/src/rpc.xml b/lib/kernel/doc/src/rpc.xml
index 6b471d0d42..4fe9b6535e 100644
--- a/lib/kernel/doc/src/rpc.xml
+++ b/lib/kernel/doc/src/rpc.xml
@@ -53,6 +53,14 @@
<c>erpc</c>, so the <c>rpc</c> module won't not suffer scalability
wise and performance wise compared to <c>erpc</c>.
</p></note>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ Blocking Signaling Over Distribution</seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ Blocking signaling can, for example, cause timeouts in <c>rpc</c>
+ to be significantly delayed.
+ </p></note>
</description>
<datatypes>
diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml
index 26a7f5646b..342fcb8b3d 100644
--- a/lib/stdlib/doc/src/gen_event.xml
+++ b/lib/stdlib/doc/src/gen_event.xml
@@ -113,6 +113,15 @@ gen_event:stop -----> Module:terminate/2
<p>Unless otherwise stated, all functions in this module fail if
the specified event manager does not exist or if bad arguments are
specified.</p>
+
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ Blocking signaling can, for example, cause call timeouts in
+ <c>gen_event</c> to be significantly delayed.
+ </p></note>
</description>
<datatypes>
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 0bbaee2fd8..ad1deed965 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -107,6 +107,15 @@ gen_server:abcast -----> Module:handle_cast/2
Processes</seeguide> in the Reference Manual for details
regarding error handling using exit signals.</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ Blocking signaling can, for example, cause call timeouts in
+ <c>gen_server</c> to be significantly delayed.
+ </p></note>
+
</description>
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 1eae53d9e4..fc7dc31a5a 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -381,6 +381,14 @@ erlang:'!' -----> Module:StateName/3
Processes</seeguide> in the Reference Manual for details regarding error
handling using exit signals.
</p>
+ <note><p>
+ For some important information about distributed signals, see the
+ <seeguide marker="system/reference_manual:processes#blocking-signaling-over-distribution">
+ <i>Blocking Signaling Over Distribution</i></seeguide> section in the
+ <i>Processes</i> chapter of the <i>Erlang Reference Manual</i>.
+ Blocking signaling can, for example, cause call timeouts in
+ <c>gen_statem</c> to be significantly delayed.
+ </p></note>
</description>
<section>
diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml
index 54d150bc28..4f1228e210 100644
--- a/system/doc/reference_manual/processes.xml
+++ b/system/doc/reference_manual/processes.xml
@@ -680,7 +680,10 @@ spawn(Module, Name, Args) -> pid()
while it can be trapped if the signal was sent due to a link.
</p>
</item>
- <tag>Blocking Signaling Over Distribution</tag>
+ <tag>
+ Blocking Signaling Over Distribution
+ <marker id="blocking-signaling-over-distribution"/>
+ </tag>
<item>
<p>
When sending a signal over a distribution channel, the sending
@@ -690,24 +693,34 @@ spawn(Module, Name, Args) -> pid()
size of the output buffer for the channel reach the <i>distribution
buffer busy limit</i>, processes sending on the channel will be
suspended until the size of the buffer shrinks below the limit.
- The size of the limit can be inspected by calling
+ </p>
+ <p>
+ Depending on the reason for why the buffer got full, the time it
+ takes before suspended processes are resumed can vary <em>very
+ much</em>. A consequence of this can, for example, be that a
+ timeout in a call to
+ <seemfa marker="kernel:erpc#call/5">erpc:call()</seemfa>
+ is significantly delayed.
+ </p>
+ <p>
+ Since this functionality has been present for so long, it is not
+ possible to remove it, but it is possible to enable <i>fully
+ asynchronous distributed signaling</i> on a per process level
+ using <seeerl marker="erts:erlang#process_flag_async_dist">
+ <c>process_flag(async_dist, Bool)</c></seeerl> which can be
+ used to solve problems occuring due to blocking signaling.
+ However, note that you need to make sure that flow control for
+ data sent using <i>fully asynchronous distributed signaling</i>
+ is implemented, or that the amount of such data is known to
+ always be limited; otherwise, you may get into a situation with
+ excessive memory usage.
+ </p>
+ <p>
+ The size of the <i>distribution buffer busy limit</i> can be
+ inspected by calling
<seeerl marker="erts:erlang#system_info_dist_buf_busy_limit">
<c>erlang:system_info(dist_buf_busy_limit)</c></seeerl>.
- Since this functionality has been present for so long, it is not
- possible to remove it, but it is possible to increase the limit
- to a point where it more or less never is reached using the
- <c>erl</c> command line argument
- <seecom marker="erts:erl#+zdbbl"><c>+zdbbl</c></seecom>. Note
- that if you do raise the limit like this, you need to take care
- of flow control yourself to ensure that you do not get into a
- situation with excessive memory usage.</p>
- <change><p>As of OTP 25.3 it is
- also possible to enable <i>fully asynchronous distributed
- signaling</i> on a per process level using
- <seeerl marker="erts:erlang#process_flag_async_dist">
- <c>process_flag(async_dist, Bool)</c></seeerl>. Also in this case
- you need to take care of flow control yourself.
- </p></change>
+ </p>
</item>
</taglist>
<p>
--
2.35.3
