File 3543-erts-kernel-stdlib-Documentation-about-blo... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 3543-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.
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 <change>
 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.
 
 </warning>
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </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.
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 </desc>
 </func>
 
@@ -3674,6 +3692,12 @@ is_process_alive(P2Pid),
 	 chapter of the ERTS User's Guide.
 	
 
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 	Failure:
 	<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.
 </note>
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </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).
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 </desc>
 </func>
 
@@ -7491,6 +7527,12 @@ true</pre>
 instead.
 </item>
 </taglist>
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 <warning>
 As with <c>erlang:send_nosuspend/2,3</c>: use with extreme
 care.
@@ -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>.
 	
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 </desc>
 </func>
 
@@ -13808,7 +13856,12 @@ end</code>
 	 protocol</seeguide> can be found in the Distribution Protocol
 	 chapter of the ERTS User's Guide.
 	
-
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ </note>
 
 	 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.
 
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ Blocking signaling can, for example, cause timeouts in <c>erpc</c>
+ to be significantly delayed.
+ </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>.
 </note>
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ Blocking signaling can, for example, cause timeouts in <c>rpc</c>
+ to be significantly delayed.
+ </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
 Unless otherwise stated, all functions in this module fail if
 the specified event manager does not exist or if bad arguments are
 specified.
+
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ Blocking signaling can, for example, cause call timeouts in
+ <c>gen_event</c> to be significantly delayed.
+ </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.
 
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ Blocking signaling can, for example, cause call timeouts in
+ <c>gen_server</c> to be significantly delayed.
+ </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.
 
+ <note>
+ 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
+ Processes chapter of the Erlang Reference Manual.
+ Blocking signaling can, for example, cause call timeouts in
+ <c>gen_statem</c> to be significantly delayed.
+ </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.
 	 
 	</item>
-	<tag>Blocking Signaling Over Distribution</tag>
+	<tag>
+ Blocking Signaling Over Distribution
+ <marker id="blocking-signaling-over-distribution"/>
+ </tag>
 	<item>
 	 
 	 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 distribution
 	 buffer busy limit, 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
+ 
+ 
+ Depending on the reason for why the buffer got full, the time it
+ takes before suspended processes are resumed can vary very
+ much. 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.
+ 
+ 
+ Since this functionality has been present for so long, it is not
+	 possible to remove it, but it is possible to enable fully
+ asynchronous distributed signaling 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 fully asynchronous distributed signaling
+ 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.
+ 
+ 
+	 The size of the distribution buffer busy limit 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.
- <change>As of OTP 25.3 it is
- also possible to enable fully asynchronous distributed
- signaling 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.
-	 </change>
+ 
 	</item>
 </taglist>
 
-- 
2.35.3

Places

File 3543-erts-kernel-stdlib-Documentation-about-blocking-sign.patch of Package erlang

Places