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 ++++++++++++-
 2 files changed, 26 insertions(+), 3 deletions(-)

(limited to 'erts/doc')

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
-- 
cgit v1.2.3