File 2356-Reference-manual-Improve-documentation-of-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 2356-Reference-manual-Improve-documentation-of-signals.patch of Package erlang (Revision bb8d79bc8e8772df551b96fc65be3d2d)

Currently displaying revision bb8d79bc8e8772df551b96fc65be3d2d , Show latest

From cf5c55895bd5724b30c4e7dbb5c3f9b7f63e28a2 Mon Sep 17 00:00:00 2001
From: Rickard Green <rickard@erlang.org>
Date: Tue, 23 Mar 2021 23:03:40 +0100
Subject: [PATCH 6/6] Reference manual: Improve documentation of signals

---
 erts/doc/src/communication.xml              |  38 +-
 erts/doc/src/erl_dist_protocol.xml          |   4 +-
 erts/doc/src/erlang.xml                     |   4 +-
 system/doc/reference_manual/expressions.xml |   8 +-
 system/doc/reference_manual/processes.xml   | 516 +++++++++++++++++++-
 5 files changed, 525 insertions(+), 45 deletions(-)

diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index 0dbbba6795..382f9a8a8c 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -433,9 +433,11 @@ end</pre>
 
 Fetches a received message present in the message queue of
 the process. The patterns <c>Pattern</c> are sequentially matched
- against the first message in time order in the message queue, then
- the second, and so on. If a match succeeds and the optional
- guard sequence <c>GuardSeq</c> is true, the corresponding
+ against the first message in the message queue, then the second,
+ and so on. Messages in the message queue are
+ <seealso marker="processes#message-queue-order">ordered in the
+ order they were received</seealso>. If a match succeeds and the
+ optional guard sequence <c>GuardSeq</c> is true, the corresponding
 <c>Body</c> is evaluated. The matching message is consumed, that
 is, removed from the mail queue, while any other messages in
 the mail queue remain unchanged.
diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml
index 3808ca74d9..204cbf36fc 100644
--- a/system/doc/reference_manual/processes.xml
+++ b/system/doc/reference_manual/processes.xml
@@ -185,15 +185,507 @@ spawn(Module, Name, Args) -> pid()
 </section>
 
 <section>
- <title>Message Sending</title>
- Processes communicate by sending and receiving messages.
- Messages are sent by using
- the <seealso marker="expressions#send">send operator !</seealso>
- and received by calling
- <seealso marker="expressions#receive">receive</seealso>.
- Message sending is asynchronous and safe, the message is
- guaranteed to eventually reach the recipient, provided that
- the recipient exists.
+ <title>Signals</title>
+ 
+ <marker id="message-sending"/>
+ All communication between Erlang processes and Erlang ports is done by
+ sending and receiving asynchronous signals. The most common signals are
+ Erlang message signals. A message signal can be sent using the
+ <seealso marker="expressions#send">send operator <c>!</c></seealso>.
+ A received message can be fetched from the message queue by the
+ receiving process using the
+ <seealso marker="expressions#receive"><c>receive</c></seealso>
+ expression.
+ 
+
+ <marker id="sync-comm"/>
+ 
+ Synchronous communication can be broken down into multiple asynchronous
+ signals. An example of such a synchronous communication is a call to the
+ <seealso marker="erts:erlang#process_info/2"><c>erlang:process_info/2</c></seealso>
+ BIF when the first argument does not equal the process identifier of
+ the calling process. The caller sends an asynchronous signal requesting
+ information, and then blocks waiting for the reply signal containing
+ the requested information. When the request signal reaches its
+ destination, the destination process replies with the requested
+ information.
+ 
+
+ <section>
+ <title>Sending Signals</title>
+
+ 
+	There are many signals that processes and ports use to communicate. The list below
+	contains the most important signals. In all the
+	cases of request/reply signal pairs, the request signal is sent
+	by the process calling the specific BIF, and the reply signal is sent
+	back to it when the requested operation has been performed.
+ 
+ <taglist>
+	<tag><c>message</c></tag>
+	<item>
+	 Sent when using the
+	 <seealso marker="expressions#send">send operator <c>!</c></seealso>,
+	 or when calling one of the
+	 <seealso marker="erts:erlang#send/2"><c>erlang:send/2,3</c></seealso>
+	 or
+	 <seealso marker="erts:erlang#send_nosuspend/2"><c>erlang:send_nosuspend/2,3</c></seealso>
+	 BIFs.
+	</item>
+
+	<tag><c>link</c></tag>
+	<item>
+	 Sent when calling the
+	 <seealso marker="erts:erlang#link/1">link/1</seealso> BIF.
+	</item>
+
+	<tag><c>unlink</c></tag>
+	<item>
+	 Sent when calling the
+	 <seealso marker="erts:erlang#unlink/1">unlink/1</seealso> BIF.
+	</item>
+
+	<tag><c>exit</c></tag>
+	<item>
+	 Sent either when explicitly sending an <c>exit</c> signal by
+	 calling the
+	 <seealso marker="erts:erlang#exit/2">exit/2</seealso> BIF, or when
+	 a <seealso marker="#sending_exit_signals">linked process
+	 terminates</seealso>. If the signal is sent due to a link, the
+	 signal is sent after all <seealso marker="#visible-resources">
+	 directly visible Erlang resources</seealso> used by the
+	 process have been released.
+	</item>
+
+	<tag><c>monitor</c></tag>
+	<item>
+	 Sent when calling one of the
+	 <seealso marker="erts:erlang#monitor/3">monitor/2,3</seealso> BIFs.
+	</item>
+
+	<tag><c>demonitor</c></tag>
+	<item>
+	 Sent when calling one of the
+	 <seealso marker="erts:erlang#demonitor/1">demonitor/1,2</seealso>
+	 BIFs, or when a process monitoring another process terminates.
+	</item>
+
+	<tag><c>down</c></tag>
+	<item>
+	 Sent by a <seealso marker="#monitors">monitored process or
+	 port that terminates</seealso>. The signal is sent after
+	 all <seealso marker="#visible-resources">directly visible
+	 Erlang resources</seealso> used by the process or the port
+	 have been released.
+	</item>
+
+	<tag><c>change</c></tag>
+	<item>
+	 Sent by the <seealso marker="#runtime-service">clock
+	 service</seealso> on the local runtime system, when the
+	 <seealso marker="erts:erlang#time_offset/0">time offset</seealso>
+	 changes, to processes which have
+	 <seealso marker="erts:erlang#monitor/2">monitored the
+	 <c>time_offset</c></seealso>.
+	</item>
+
+	<tag><c>group_leader</c></tag>
+	<item>
+	 Sent when calling the
+	 <seealso marker="erts:erlang#group_leader/2">group_leader/2</seealso>
+	 BIF.
+	</item>
+
+	<tag>
+	 <c>spawn_request</c>/<c>spawn_reply</c>,
+	 <c>open_port_request</c>/<c>open_port_reply</c>
+	</tag>
+	<item>
+	 Sent due to a call to one of the
+ 	 <seealso marker="erts:erlang#spawn/4"><c>spawn/1,2,3,4</c></seealso>,
+	 <seealso marker="erts:erlang#spawn_link/4"><c>spawn_link/1,2,3,4</c></seealso>,
+	 <seealso marker="erts:erlang#spawn_monitor/4"><c>spawn_monitor/1,2,3,4</c></seealso>,
+	 <seealso marker="erts:erlang#spawn_opt/5"><c>spawn_opt/2,3,4,5</c></seealso>,
+	 <seealso marker="erts:erlang#spawn_request/5"><c>spawn_request/1,2,3,4,5</c></seealso>,
+	 or <seealso marker="erts:erlang#open_port/2"><c>erlang:open_port/2</c></seealso>
+	 BIFs. The request signal is sent to the
+	 <seealso marker="#runtime-service">spawn service</seealso> which
+	 responds with the reply signal.
+	</item>
+
+	<tag><c>alive_request</c>/<c>alive_reply</c></tag>
+	<item>
+	 Sent due to a call to the
+	 <seealso marker="erts:erlang#is_process_alive/1">is_process_alive/1</seealso>
+	 BIF.
+	</item>
+
+	<tag>
+	 <c>garbage_collect_request</c>/<c>garbage_collect_reply</c>,
+	 <c>check_process_code_request</c>/<c>check_process_code_reply</c>,
+	 <c>process_info_request</c>/<c>process_info_reply</c>
+	</tag>
+	<item>
+	 Sent due to a call to one of the
+	 <seealso marker="erts:erlang#garbage_collect/1">garbage_collect/1,2</seealso>,
+	 <seealso marker="erts:erlang#check_process_code/2">erlang:check_process_code/2,3</seealso>,
+	 or <seealso marker="erts:erlang#process_info/2">process_info/1,2</seealso>
+	 BIFs. Note that if the request is directed towards the caller itself
+	 and it is a synchronous request, no signaling will be performed
+	 and the caller will instead synchronously perform the request before
+	 returning from the BIF.
+	</item>
+
+	<tag><c>port_command</c>, <c>port_connect</c>, <c>port_close</c></tag>
+	<item>
+	 Sent by a process to a port on the local node using the
+	 <seealso marker="expressions#send">send operator <c>!</c></seealso>,
+	 or by calling one of the
+	 <seealso marker="erts:erlang#send/2"><c>send()</c></seealso>
+	 BIFs. The signal is sent by passing a term on the format
+	 <c>{Owner, {command, Data}}</c>, <c>{Owner, {connect, Pid}}</c>,
+	 or <c>{Owner, close}</c> as message.
+	</item>
+
+	<tag>
+	 <c>port_command_request</c>/<c>port_command_reply</c>,
+	 <c>port_connect_request</c>/<c>port_connect_reply</c>,
+	 <c>port_close_request</c>/<c>port_close_reply</c>,
+	 <c>port_control_request</c>/<c>port_control_reply</c>,
+	 <c>port_call_request</c>/<c>port_call_reply</c>,
+	 <c>port_info_request</c>/<c>port_info_reply</c>
+	</tag>
+	<item>
+	 Sent due to a call to one of the
+ 	 <seealso marker="erts:erlang#port_command/2"><c>erlang:port_command/2,3</c></seealso>,
+	 <seealso marker="erts:erlang#port_connect/2"><c>erlang:port_connect/2</c></seealso>,
+	 <seealso marker="erts:erlang#port_close/1"><c>erlang:port_close/1</c></seealso>,
+	 <seealso marker="erts:erlang#port_control/3"><c>erlang:port_control/3</c></seealso>,
+	 <seealso marker="erts:erlang#port_call/3"><c>erlang:port_call/3</c></seealso>,
+	 <seealso marker="erts:erlang#port_info/1"><c>erlang:port_info/1,2</c></seealso>
+	 BIFs. The request signal is sent to a port on the local node 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>
+	</tag>
+	<item>
+	 Sent due to a call to one of the
+ <seealso marker="erts:erlang#send_after/3"><c>erlang:send_after/3,4</c></seealso>,
+ <seealso marker="erts:erlang#start_timer/3"><c>erlang:start_timer/3,4</c></seealso>,
+	 or
+	 <seealso marker="erts:erlang#cancel_timer/1"><c>erlang:cancel_timer/1,2</c></seealso>
+	 BIFs. The request signal is sent to the
+	 <seealso marker="#runtime-service">timer service</seealso> which
+	 responds with the reply signal.
+	</item>
+	
+ </taglist>
+
+ <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 not preserved. Note
+	that this does not violate the
+	<seealso marker="#signal-delivery">signal ordering
+	guarantee</seealso> of the language.
+ 
+
+ 
+	The realization of the signals described above may change both at
+	runtime and due to changes in implementation. You may be able to
+	detect such changes using <c>receive</c> tracing or by inspecting
+	message queues. However, these are internal implementation details of
+	the runtime system that you should not rely on. As an example,
+	many of the reply signals above are ordinary message signals.
+	When the operation is synchronous, the reply signals do not have to be
+	message signals. The current implementation takes advantage of this
+	and, depending on the state of the system, use alternative ways of
+	delivering the reply signals. The implementation of these reply signals
+	may also, at any time, be changed to not use message signals where it
+	previously did.
+ 
+
+ </section>
+
+ <section>
+ <title>Receiving Signals</title>
+ 
+	When a signal is received by a process, some kind of action is
+	taken. The specific action taken depends on the signal type,
+	contents of the signal, and the state of the receiving process.
+	Actions taken for the most common signals:
+ 
+ <taglist>
+	<tag><c>message</c></tag>
+	<item>
+	 If the message signal was sent using a
+	 <seealso marker="#process-aliases">process alias</seealso>
+	 that is no longer active, the message signal will be dropped;
+	 otherwise, if the alias is still active or the message signal
+	 was sent by other means, the message is added to the end of the
+	 message queue. When the message has been added to the message
+	 queue, the receiving process can fetch the message from the
+	 message queue using the
+	 <seealso marker="expressions#receive"><c>receive</c></seealso>
+	 expression.
+	</item>
+
+	<tag><c>link</c>, <c>unlink</c></tag>
+	<item>
+	 Very simplified it can be viewed as updating process local
+	 information about the link. A detailed description of the
+	 <seealso marker="erts:erl_dist_protocol#link_protocol">link
+	 protocol</seealso> can be found in the Distribution Protocol
+	 chapter of the ERTS User's Guide.
+	</item>
+
+	<tag><c>exit</c></tag>
+	<item>
+	 Set the receiver in an exiting state, drop the signal, or convert
+	 the signal into a message and add it to the end of the message
+	 queue. If the receiver is set in an exiting state, no more Erlang
+	 code will be executed and the process is scheduled for termination.
+	 The section <seealso marker="#receiving_exit_signals">Receiving
+	 Exit Signals</seealso> below gives more details on the
+	 action taken when an <c>exit</c> signal is received.
+	</item>
+
+	<tag><c>monitor</c>, <c>demonitor</c></tag>
+	<item>
+	 Update process local information about the monitor.
+	</item>
+
+	<tag><c>down</c>, <c>change</c></tag>
+	<item>
+	 Convert into a message if the corresponding monitor is still
+	 active; otherwise, drop the signal. If the signal is converted
+	 into a message, it is also added to the end of the message
+	 queue.
+	</item>
+
+	<tag><c>group_leader</c></tag>
+	<item>
+	 Change the group leader of the process.
+	</item>
+
+	<tag><c>spawn_reply</c></tag>
+	<item>
+	 Convert into a message, or drop the signal depending on the reply
+	 and how the <c>spawn_request</c> signal was configured. If the
+	 signal is converted into a message it is also added to the end
+	 of the message queue. For more information see the
+	 <seealso marker="erts:erlang#spawn_request/5"><c>spawn_request()</c></seealso>
+	 BIF.
+	</item>
+
+	<tag><c>alive_request</c></tag>
+	<item>
+	 Schedule execution of the is alive test. If the process
+	 is in an exiting state, the is alive test will not be
+	 executed until after all
+	 <seealso marker="#visible-resources">directly visible Erlang
+	 resources</seealso> used by the process have been released.
+	 The <c>alive_reply</c> will be sent after the is alive
+	 test has executed.
+	</item>
+	
+	<tag>
+	 <c>process_info_request</c>,
+	 <c>garbage_collect_request</c>,
+	 <c>check_process_code_request</c>
+	</tag>
+	<item>
+	 Schedule execution of the requested operation. The reply signal
+	 will be sent when the operation has been executed.
+	</item>
+ </taglist>
+ 
+	Note that some actions taken when a signal is received involves
+	scheduling further actions which will result in a reply
+	signal when these scheduled actions have completed. This implies that
+	the reply signals may be sent in a different order than the order of
+	the incoming signals that triggered these operations. This does,
+	however, not violate the
+	<seealso marker="#signal-delivery">signal ordering
+	guarantee</seealso> of the language.
+ 
+
+ <marker id="message-queue-order"/>
+ 
+	The order of messages in the message queue of a process reflects the
+	order in which the signals corresponding to the messages has been
+	received since <seealso marker="processes#receiving-signals">all
+	signals	that add messages to the message queue add them at the end of
+	the message queue</seealso>. Messages corresponding to signals from
+	the same sender are also ordered in the same order as the signals were
+	sent due to the <seealso marker="processes#signal-delivery">signal
+	ordering guarantee</seealso> of the language.
+ 
+
+ </section>
+ 
+ <section>
+ <marker id="visible-resources"/>
+ <title>Directly Visible Erlang Resources</title>
+ 
+	As described above, <c>exit</c> signals due to links, <c>down</c>
+	signals, and reply signals from an exiting process due to
+	<c>alive_request</c>s are not sent until all directly visible
+	Erlang resources held by the terminating process have been
+	released. With directly visible Erlang resources we here mean
+	all resources made available by the language excluding resources held
+	by heap data, dirty native code execution and the process identifier of
+	the terminating process. Examples of directly visible Erlang
+	resources are <seealso marker="#registered-processes">registered
+	name</seealso> and <seealso marker="stdlib:ets">ETS</seealso> tables.
+ 
+ <section>
+	<title>The Excluded Resources</title>
+	
+	 The process identifier of the process cannot be released for
+	 reuse until everything regarding the process has been released.
+	
+	
+	 A process executing dirty native code in a NIF when it receives
+	 an exit signal will be set into an exiting state even if it is
+	 still executing dirty native code. Directly visible Erlang
+	 resources will be released, but the runtime system cannot
+	 force the native code to stop executing. The runtime system tries
+	 to prevent the execution of the dirty native code from effecting
+	 other processes by, for example, disabling functionality such as
+	 <seealso marker="erts:erl_nif#enif_send"><c>enif_send()</c></seealso>
+	 when used from a terminated process, but if the NIF is not well
+	 behaved it can still effect other processes. A well behaved dirty
+	 NIF should test if
+	 <seealso marker="erts:erl_nif#enif_is_current_process_alive">the
+	 process it is executing in has exited</seealso>, and if so stop
+	 executing.
+	
+	
+	 In the general case, the heap of a process cannot be removed before
+	 all signals that it needs to send have been sent. Resources held
+	 by heap data are the memory blocks containing the heap, but also
+	 include things referred to from the heap such as off heap binaries,
+	 and resources held via NIF
+	 <seealso marker="erts:erl_nif#resource_objects">resource
+	 objects</seealso> on the heap.
+	
+ </section>
+ </section>
+
+ <section>
+ <marker id="signal-delivery"/>
+ <title>Delivery of Signals</title>
+ 
+	The amount of time that passes between the time a signal is sent and
+	the arrival of the signal at the destination is unspecified but
+	positive. If the receiver has terminated, the signal does not arrive,
+	but it can trigger another signal. For example, a <c>link</c> signal
+	sent to a non-existing process triggers an <c>exit</c> signal, which
+	is sent back to where the <c>link</c> signal originated from. When
+	communicating over the distribution, signals can be lost if the
+	distribution channel goes down.
+ 
+
+ 
+	The only signal ordering guarantee given is the following: if an
+	entity sends multiple signals to the same destination entity, the
+	order is preserved; that is, if <c>A</c> sends a signal <c>S1</c> to
+	<c>B</c>, and later sends signal <c>S2</c> to <c>B</c>, <c>S1</c> is
+	guaranteed not to arrive after <c>S2</c>. Note that <c>S1</c> may,
+	or may not have been lost.
+ 
+ </section>
+
+ <section>
+ <marker id="signal-irregularities"/>
+ <title>Irregularities</title>
+ <taglist>
+	<tag>Synchronous Error Checking</tag>
+	<item>
+	 
+	 Some functionality that send signals have synchronous error
+	 checking when sending locally on a node and fail if the receiver
+	 is not present at the time when the signal is sent:
+	 
+	 <list>
+	 <item>
+	 The <seealso marker="expressions#send">send operator
+	 <c>!</c></seealso>,
+	 <seealso marker="erts:erlang#send/2"><c>erlang:send/2,3</c></seealso>,
+	 BIFs and
+	 <seealso marker="erts:erlang#send_nosuspend/2"><c>erlang:send_nosuspend/2,3</c></seealso>
+	 BIFs when the receiver is identified by a name that is
+	 expected to be registered locally.
+	 </item>
+	 <item>
+	 <seealso marker="erts:erlang#link/1"><c>erlang:link/1</c></seealso>
+	 </item>
+	 <item>
+	 <seealso marker="erts:erlang#group_leader/2"><c>erlang:group_leader/2</c></seealso>
+	 </item>
+	 </list>
+	 
+	</item>
+	<tag>Unexpected Behaviours of Exit Signals</tag>
+	<item>
+	 
+	 When a process sends an exit signal with exit reason <c>normal</c>
+	 to itself by calling <seealso marker="erts:erlang#exit/2"><c>erlang:exit(self(),
+	 normal)</c></seealso> it will be terminated
+	 <seealso marker="#receiving_exit_signals">when the <c>exit</c> signal
+	 is received</seealso>. In all other cases when an exit signal with
+	 exit reason <c>normal</c> is received, it is dropped.
+	 
+	 
+	 When an <seealso marker="#receiving_exit_signals"><c>exit</c> signal
+	 with exit reason <c>kill</c> is received</seealso>,
+	 the action taken is different depending on whether the signal was
+	 sent due to a linked process terminating, or the signal was
+	 explicitly sent using the
+	 <seealso marker="erts:erlang#exit/2"><c>exit/2</c></seealso> BIF. When
+	 sent using the <c>exit/2</c> BIF, the signal cannot be
+	 <seealso marker="erts:erlang#process_flag_trap_exit">trapped</seealso>,
+	 while it can be trapped if the signal was sent due to a link.
+	 
+	</item>
+	<tag>Blocking Signaling Over Distribution</tag>
+	<item>
+	 
+	 When sending a signal over a distribution channel, the sending
+	 process may be suspended even though the signal is supposed to be
+	 sent asynchronously. This is due to the built in flow control over
+	 the channel that has been present more or less for ever. When the
+	 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
+	 <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">
+	 <c>erlang:system_info(dist_buf_busy_limit)</c></seealso>.
+	 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
+	 <seealso marker="erts:erl#+zdbbl"><c>+zdbbl</c></seealso>. 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.
+	 
+	</item>
+ </taglist>
+ 
+	The irregularities mentioned above cannot be fixed as they have been
+	part of Erlang too long and it would break a lot of existing code.
+ 
+ </section>
+
 </section>
 
 <section>
-- 
2.26.2

Places

File 2356-Reference-manual-Improve-documentation-of-signals.patch of Package erlang (Revision bb8d79bc8e8772df551b96fc65be3d2d)

Places