Merge branch 'nybek/fix_gen_tcp_shutdown'

OTP-12797

2 files changed, 43 insertions, 4 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>
diff --git a/lib/kernel/test/gen_tcp_api_SUITE.erl b/lib/kernel/test/gen_tcp_api_SUITE.erl
index c27d265550..4a527e2f51 100644
--- a/lib/kernel/test/gen_tcp_api_SUITE.erl
+++ b/lib/kernel/test/gen_tcp_api_SUITE.erl
@@ -32,6 +32,7 @@
 	 t_connect_bad/1,
 	 t_recv_timeout/1, t_recv_eof/1,
 	 t_shutdown_write/1, t_shutdown_both/1, t_shutdown_error/1,
+	 t_shutdown_async/1,
 	 t_fdopen/1, t_fdconnect/1, t_implicit_inet6/1]).
 
 -export([getsockfd/0,closesockfd/1]).
@@ -41,7 +42,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}].
 all() -> 
     [{group, t_accept}, {group, t_connect}, {group, t_recv},
      t_shutdown_write, t_shutdown_both, t_shutdown_error,
-     t_fdopen, t_fdconnect, t_implicit_inet6].
+     t_shutdown_async, t_fdopen, t_fdconnect, t_implicit_inet6].
 
 groups() -> 
     [{t_accept, [], [t_accept_timeout]},
@@ -155,7 +156,34 @@ t_shutdown_error(Config) when is_list(Config) ->
     ?line ok = gen_tcp:close(L),
     ?line {error, closed} = gen_tcp:shutdown(L, read_write),
     ok.
-    
+
+t_shutdown_async(Config) when is_list(Config) ->
+    ?line {OS, _} = os:type(),
+    ?line {ok, L} = gen_tcp:listen(0, [{sndbuf, 4096}]),
+    ?line {ok, Port} = inet:port(L),
+    ?line {ok, Client} = gen_tcp:connect(localhost, Port,
+					 [{recbuf, 4096},
+					  {active, false}]),
+    ?line {ok, S} = gen_tcp:accept(L),
+    ?line PayloadSize = 1024 * 1024,
+    ?line Payload = lists:duplicate(PayloadSize, $.),
+    ?line ok = gen_tcp:send(S, Payload),
+    ?line case erlang:port_info(S, queue_size) of
+	      {queue_size, N} when N > 0 -> ok;
+	      {queue_size, 0} when OS =:= win32 -> ok;
+	      {queue_size, 0} = T -> ?t:fail({unexpected, T})
+	  end,
+
+    ?line ok = gen_tcp:shutdown(S, write),
+    ?line {ok, Buf} = gen_tcp:recv(Client, PayloadSize),
+    ?line {error, closed} = gen_tcp:recv(Client, 0),
+    ?line case length(Buf) of
+	      PayloadSize -> ok;
+	      Sz -> ?t:fail({payload_size,
+			     {expected, PayloadSize},
+			     {received, Sz}})
+	  end.
+
 
 %%% gen_tcp:fdopen/2