File 0810-Document-the-return-value-details-for-rpc-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0810-Document-the-return-value-details-for-rpc-call-4-and.patch of Package erlang

From 4801e39ac76728958c6a36c06c3e1af5d038862e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Fri, 8 Nov 2019 11:37:37 +0100
Subject: [PATCH] Document the return value details for rpc:call/4 and friends

OTP Technical Board decided that we will not change the
the behavior of `rpc:call/4` and friends in order to
preserve backward compatibility. Since the some of the
details of the return values can be surprising, update
the documentation without detailed description of
the return values.

https://bugs.erlang.org/browse/ERL-1066
---
 lib/kernel/doc/src/rpc.xml | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/lib/kernel/doc/src/rpc.xml b/lib/kernel/doc/src/rpc.xml
index c55454506e..0e07d334d8 100644
--- a/lib/kernel/doc/src/rpc.xml
+++ b/lib/kernel/doc/src/rpc.xml
@@ -111,6 +111,8 @@
 for efficiency reasons when very small fast functions are
 evaluated, for example, BIFs that are guaranteed not to
 suspend.
+	 See the note in <seealso marker="#call/4"><c>call/4</c></seealso>
+	 for more details of the return value.
 </desc>
 </func>
 
@@ -123,6 +125,8 @@
 <seealso marker="#block_call/4"><c>block_call/4</c></seealso>,
 but with a time-out value in the same manner as
 <seealso marker="#call/5"><c>call/5</c></seealso>.
+	 See the note in <seealso marker="#call/4"><c>call/4</c></seealso>
+	 for more details of the return value.
 </desc>
 </func>
 
@@ -133,7 +137,28 @@
 Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
 <anno>Args</anno>)</c> on node <c><anno>Node</anno></c> and returns
 the corresponding value <c><anno>Res</anno></c>, or
- <c>{badrpc, <anno>Reason</anno>}</c> if the call fails.
+ <c>{badrpc, <anno>Reason</anno>}</c> if the call fails.
+	<note>
+	 Here follows the details of what exactly is returned.
+	 <c>{badrpc, <anno>Reason</anno>}</c> will be returned in the
+	 following circumstances:
+ <list type="bulleted">
+ <item>The called function fails with an <c>exit</c> exception.</item>
+ <item>The called function fails with an <c>error</c> exception.</item>
+	 <item>The called function returns a term that matches
+	 <c>{'EXIT', _}</c>.</item>
+	 <item>The called function <c>throws</c>
+	 a term that matches <c>{'EXIT', _}</c>.</item>
+ </list>
+
+	 <c><anno>Res</anno></c> is returned in the following circumstances:
+ <list type="bulleted">
+ <item>The called function returns normally with a term that does
+	 not match <c>{'EXIT',_}</c>.</item>
+ <item>The called function <c>throw</c>s a term that does
+	 not match <c>{'EXIT',_}</c>.</item>
+ </list>
+	</note>
 </desc>
 </func>
 
@@ -147,7 +172,9 @@
 <c>{badrpc, <anno>Reason</anno>}</c> if the call fails.
 <c><anno>Timeout</anno></c> is
 a time-out value in milliseconds. If the call times out,
- <c><anno>Reason</anno></c> is <c>timeout</c>.
+ <c><anno>Reason</anno></c> is <c>timeout</c>.
+	 See the note in <seealso marker="#call/4"><c>call/4</c></seealso>
+	 for more details of the return value.
 If the reply arrives after the call times out, no message
 contaminates the caller's message queue, as this
 function spawns off a middleman process to act as (a void)
@@ -306,6 +333,8 @@
 the tuple <c>{value, <anno>Val</anno>}</c> when the computation is
 finished, or <c>timeout</c> when <c><anno>Timeout</anno></c>
 milliseconds has elapsed.
+	 See the note in <seealso marker="#call/4"><c>call/4</c></seealso>
+	 for more details of <anno>Val</anno>.
 <note>
 This function must be called by the same process from which
 <seealso marker="#async_call/4"><c>async_call/4</c></seealso>
@@ -424,6 +453,8 @@
 <seealso marker="#async_call/4"><c>async_call/4</c></seealso>
 was made otherwise it will never return.
 </note>
+	See the note in <seealso marker="#call/4"><c>call/4</c></seealso>
+	for more details of the return value.
 </desc>
 </func>
 </funcs>
-- 
2.16.4

Places

File 0810-Document-the-return-value-details-for-rpc-call-4-and.patch of Package erlang

Places