Fix gen_tcp:shutdown/2 by making it asynchronous

If the driver queue is empty, or the user is requesting a 'read'
shutdown, then the shutdown() syscall is performed synchronously, as
per the old version of shutdown/2.

However, if the user is requesting a 'write' or 'read_write' shutdown,
and there is data in the driver queue for the socket, then the
shutdown() syscall is delayed and handled asynchronously when the
driver queue is written out.

This version of shutdown solves a number of issues with the old
version. The two main solutions it offers are:

 * It doesn't block when the TCP peer is idle or slow. This is the
   expected behaviour when shutdown() is called: the caller needs
   to be able to continue reading from the socket, not be prevented
   from doing so.

 * It doesn't truncate the output. The current version of
   gen_tcp:shutdown/2 will truncate any outbound data in the driver
   queue after about 10 seconds if the TCP peer is idle of slow. Worse
   yet, it doesn't even inform anyone that the data has been
   truncated: 'ok' is returned to the caller; and a FIN rather than
   an RST is sent to the TCP peer.

For a detailed description of all the problems with the old version
of shutdown, please see the EEP Light that was written to justify
this patch.

1 files changed, 13 insertions, 2 deletions

diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index 820ecd1e30..71ef5cd48f 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -347,11 +347,22 @@ do_recv(Sock, Bs) ->
     </func>
     <func>
       <name name="shutdown" arity="2"/>
-      <fsummary>Immediately close a socket</fsummary>
+      <fsummary>Asynchronously close a socket</fsummary>
       <desc>
-        <p>Immediately close a socket in one or two directions.</p>
+        <p>Close a socket in one or two directions.</p>
         <p><c><anno>How</anno> == write</c> means closing the socket for writing,
           reading from it is still possible.</p>
+        <p>If <c><anno>How</anno> == read</c>, or there is no outgoing
+          data buffered in the <c><anno>Socket</anno></c> port,
+          then the socket is shutdown immediately and any error encountered
+          is returned in <c><anno>Reason</anno></c>.</p>
+        <p>If there is data buffered in the socket port, then the attempt
+          to shutdown the socket is postponed until that data is written to the
+          kernel socket send buffer. Any errors encountered will result
+          in the socket being closed and <c>{error, closed}</c> being returned
+          on the next
+          <seealso marker="gen_tcp#recv/2">recv/2</seealso> or
+          <seealso marker="gen_tcp#send/2">send/2</seealso>.</p>
         <p>To be able to handle that the peer has done a shutdown on
           the write side, the <c>{exit_on_close, false}</c> option
           is useful.</p>