File 3581-Improve-receive-docs.patch of Package erlang
From 18e9843e44b07d3fb5bc0e31702d7e2ea462e3c8 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Thu, 6 May 2021 15:15:45 +0200
Subject: [PATCH] Improve receive docs
Clarify message matching order; first all patterns then next message
in queue.
Rename "mailbox" and "mail queue" to message queue.
receive after limit is almost 50 days.
---
system/doc/reference_manual/expressions.xml | 46 ++++++++++-----------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index 382f9a8a8c..8c03c19d89 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -432,15 +432,17 @@ receive
end</pre>
<p>
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 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.</p>
+ the process. The first message in the message queue is matched
+ sequentially against the patterns from top to bottom. If no
+ match was found, the matching sequence is repeated for the second
+ message in the queue, and so on. Messages are queued in the
+ <seealso marker="processes#message-queue-order">order they were
+ received</seealso>. If a match succeeds, that
+ is, if the <c>Pattern</c> matches and the optional guard sequence
+ <c>GuardSeq</c> is true, then the message is removed from the message
+ queue and the corresponding <c>Body</c> is evaluated. All other
+ messages in the message queue remain unchanged.
+ </p>
<p>The return value of <c>Body</c> is the return value of
the <c>receive</c> expression.</p>
<p><c>receive</c> never fails. The execution is suspended, possibly
@@ -470,13 +472,21 @@ after
ExprT ->
BodyT
end</pre>
- <p><c>ExprT</c> is to evaluate to an integer. The highest allowed
- value is 16#FFFFFFFF, that is, the value must fit in 32 bits.
- <c>receive..after</c> works exactly as <c>receive</c>, except
+ <p><c>receive..after</c> works exactly as <c>receive</c>, except
that if no matching message has arrived within <c>ExprT</c>
milliseconds, then <c>BodyT</c> is evaluated instead. The
return value of <c>BodyT</c> then becomes the return value
- of the <c>receive..after</c> expression.</p>
+ of the <c>receive..after</c> expression. <c>ExprT</c> is to
+ evaluate to an integer, or the atom <c>infinity</c>. The allowed
+ integer range is from 0 to 4294967295, that is, the longest possible
+ timeout is almost 50 days. With a zero value the timeout occurs
+ immediately if there is no matching message in the message queue.
+ </p>
+ <p>
+ The atom <c>infinity</c> will make the process wait indefinitely for a
+ matching message. This is the same as not using a timeout. It can be
+ useful for timeout values that are calculated at runtime.
+ </p>
<p><em>Example:</em></p>
<pre>
wait_for_onhook() ->
@@ -514,16 +524,6 @@ timer(Pid) ->
5000 ->
Pid ! timeout
end.</pre>
- <p>There are two special cases for the timeout value <c>ExprT</c>:</p>
- <taglist>
- <tag><c>infinity</c></tag>
- <item>The process is to wait indefinitely for a matching message;
- this is the same as not using a timeout. This can be
- useful for timeout values that are calculated at runtime.</item>
- <tag>0</tag>
- <item>If there is no matching message in the mailbox, the timeout
- occurs immediately.</item>
- </taglist>
</section>
<section>
--
2.26.2
