From 043cb47a1967a63b316c7bd4cb4232f2e9b0f895 Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Tue, 30 Apr 2019 15:06:15 +0200
Subject: [esock|doc] Add text about the abort message

If another process closes the socket, the caller will
receive an abort message instead (of the select message).

OTP-15731
---
 erts/doc/src/socket.xml         |  16 ++++++++++++++--
 erts/doc/src/socket_usage.xml   |  13 ++++++++++++-
 erts/preloaded/ebin/socket.beam | Bin 74628 -> 74636 bytes
 erts/preloaded/src/socket.erl   |   2 +-
 4 files changed, 27 insertions(+), 4 deletions(-)

(limited to 'erts')

diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml
index 3ff0eb4e1b..f9dd9575f4 100644
--- a/erts/doc/src/socket.xml
+++ b/erts/doc/src/socket.xml
@@ -44,15 +44,27 @@
       <p>Some functions allow for an <i>asynchronous</i> call.
       This is achieved by setting the <c>Timeout</c> argument to
       <c>nowait</c>. For instance, if calling the
-      <seealso marker="#recv/3"><c>recv/3</c></seealso>
+      <seealso marker="#recv_async"><c>recv/3</c></seealso>
       function with Timeout set to <c>nowait</c> (<c>recv(Sock, 0, nowait)</c>)
       when there is actually nothing to read, it will return with
       <c>{ok, SelectInfo}</c>. When data eventually arrives a 'select' message
       will be sent to the caller:
-      <c>{'$socket', Sock, select, Info}</c>. The caller can now make another
+      <list type="ordered">
+	<item><c>{'$socket', Sock, select, Info}</c></item>
+      </list>
+      The caller can now make another
       call to the recv function and now expect data.</p>
       <p>Note that all other users are <em>locked out</em> until the
       'current user' has called the function (recv in this case).</p>
+      <p>Another message the user must be prepared for (when making asynchronous
+      calls) is the <c>abort</c> message:
+      <list type="ordered">
+	<item><c>{'$socket', Sock, abort, Reason}</c></item>
+      </list>
+      This message indicates
+      that the (asynchronous) operation has been aborted.
+      If, for instance, the socket has been
+      closed (by another process), <c>Reason</c> will be <c>{Ref, closed}</c>. </p>
     </note>
     <note>
       <p>There is currently <em>no</em> support for Windows. </p>
diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml
index 3d18bd1af7..fcfe9b54ec 100644
--- a/erts/doc/src/socket_usage.xml
+++ b/erts/doc/src/socket_usage.xml
@@ -56,8 +56,19 @@
       when there is actually nothing to read, it will return with
       <c>{ok, SelectInfo}</c>. When data eventually arrives a 'select message'
       will be sent to the caller:
-      <c>{'$socket', Sock, select, Info}</c>. The caller can make another
+      <list type="ordered">
+	<item><c>{'$socket', Sock, select, Info}</c></item>
+      </list>
+      The caller can then make another
       call to the recv function and now expect data.</p>
+      <p>The user must also be prepared to receive an abort message:
+      <list type="ordered">
+	<item><c>{'$socket', Sock, abort, Reason}</c></item>
+      </list>
+      If the operation is aborted
+      for whatever reason (e.g. if the socket is closed "by someone else").
+      The <c>Reason</c> part contains the abort reason (in case the socket
+      has been closed <c>Reason = {Ref, closed}</c>). </p>
       <p>Note that all other users are <em>locked out</em> until the
       'current user' has called the function (recv in this case). So either
       immediately call the function or
diff --git a/erts/preloaded/ebin/socket.beam b/erts/preloaded/ebin/socket.beam
index 892aab1fa0..7f5a27c980 100644
Binary files a/erts/preloaded/ebin/socket.beam and b/erts/preloaded/ebin/socket.beam differ
diff --git a/erts/preloaded/src/socket.erl b/erts/preloaded/src/socket.erl
index 59bef4b3b7..ec63eeba64 100644
--- a/erts/preloaded/src/socket.erl
+++ b/erts/preloaded/src/socket.erl
@@ -1794,7 +1794,7 @@ recv(Socket, Length) ->
       Flags  :: recv_flags(),
       Data   :: binary(),
       Reason :: term()
-                ; (Socket, Length, nowait) -> {ok, Data} |
+                ; (Socket, Length, Timeout :: nowait) -> {ok, Data} |
                                               {ok, SelectInfo} |
                                               {ok, {Data, SelectInfo}} |
                                               {error, Reason} when
-- 
cgit v1.2.3