[kernel|esock] Fixed doc for socket:cancel/2

And also fixed all "resulting (dialyzer) issues..."

OTP-18029

3 files changed, 82 insertions, 18 deletions

diff --git a/lib/kernel/doc/src/socket.xml b/lib/kernel/doc/src/socket.xml
index 408da2b987..2861108da6 100644
--- a/lib/kernel/doc/src/socket.xml
+++ b/lib/kernel/doc/src/socket.xml
@@ -1591,7 +1591,72 @@
 
     <func>
       <name name="cancel" arity="2" clause_i="1" since="OTP 22.1"/>
-      <name name="cancel" arity="2" clause_i="2" since="OTP-18029"/>
+      <fsummary>Cancel an asynchronous request.</fsummary>
+      <desc>
+	<p>Cancel an asynchronous (select) request.</p>
+	<p>
+	  Call this function in order to cancel a previous
+	  asynchronous call to, e.g.
+	  <seemfa marker="#recv/3"><c>recv/3</c></seemfa>.
+	</p>
+        <p>
+          An ongoing asynchronous operation blocks the socket
+          until the operation has been finished in good order,
+          or until it has been cancelled by this function.
+        </p>
+        <p>
+          Any other process that tries an operation
+          of the same basic type (accept / send / recv) will be
+          enqueued and notified with the regular <c>select</c>
+          mechanism for asynchronous operations
+          when the current operation and all enqueued before it
+          has been completed.
+        </p>
+        <p>
+	  If <c><anno>SelectInfo</anno></c> does not match an
+          operation in progress for the calling process,
+          this function returns
+          <c>{error,&nbsp;{invalid,&nbsp;SelectInfo}}</c>.
+        </p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="cancel" arity="2" clause_i="2" since="OTP 26.0"/>
+      <fsummary>Cancel an asynchronous request.</fsummary>
+      <desc>
+	<p>Cancel an asynchronous (completion) request.</p>
+	<p>
+	  Call this function in order to cancel a previous
+	  asynchronous call to, e.g.
+	  <seemfa marker="#recv/3"><c>recv/3</c></seemfa>.
+	</p>
+        <p>
+          An ongoing asynchronous operation blocks the socket
+          until the operation has been finished in good order,
+          or until it has been cancelled by this function.
+        </p>
+        <p>
+          Any other process that tries an operation
+          of the same basic type (accept / send / recv) will be
+          enqueued and notified with the regular <c>select</c>
+          mechanism for asynchronous operations
+          when the current operation and all enqueued before it
+          has been completed.
+        </p>
+        <p>
+	  If <c><anno>CompletionInfo</anno></c> does not match an
+          operation in progress for the calling process,
+          this function returns
+          <c>{error,&nbsp;{invalid,&nbsp;CompletionInfo}}</c>.
+        </p>
+      </desc>
+    </func>
+
+    <!--
+    <func>
+      <name name="cancel" arity="2" clause_i="1" since="OTP 22.1"/>
+      <name name="cancel" arity="2" clause_i="2" since="OTP 26.0"/>
       <fsummary>Cancel an asynchronous request.</fsummary>
       <desc>
 	<p>Cancel an asynchronous request.</p>
@@ -1622,6 +1687,7 @@
         </p>
       </desc>
     </func>
+    -->
 
     <func>
       <name name="close" arity="1" since="OTP 22.0"/>
diff --git a/lib/kernel/src/gen_tcp_socket.erl b/lib/kernel/src/gen_tcp_socket.erl
index d092faf213..fb0f807cc1 100644
--- a/lib/kernel/src/gen_tcp_socket.erl
+++ b/lib/kernel/src/gen_tcp_socket.erl
@@ -729,11 +729,9 @@ socket_close(Socket) ->
 -compile({inline, [socket_cancel/2]}).
 socket_cancel(Socket, SelectInfo) ->
     case socket:cancel(Socket, SelectInfo) of
-        ok -> ok;
-        {error, closed} -> ok;
-
-        %% Race - shall we await the message or just ignore?
-        {error, select_sent} -> ok
+        ok                 -> ok;
+        {error, closed}    -> ok;
+        {error, _} = ERROR -> ERROR
 
     end.
 
@@ -1579,7 +1577,7 @@ handle_event(
      info = SelectInfo, from = From,
      listen_socket = ListenSocket},
   {P, D}) ->
-    socket_cancel(ListenSocket, SelectInfo),
+    _ = socket_cancel(ListenSocket, SelectInfo),
     {next_state, 'closed', {P, D},
      [{reply, From, {error, timeout}}]};
 handle_event(Type, Content, #accept{} = State, P_D) ->
@@ -1665,7 +1663,7 @@ handle_event(
   {timeout, connect}, connect,
   #connect{info = SelectInfo, from = From},
   {#params{socket = Socket} = _P, _D} = P_D) ->
-    socket_cancel(Socket, SelectInfo),
+    _ = socket_cancel(Socket, SelectInfo),
     _ = socket_close(Socket),
     {next_state, 'closed', P_D,
      [{reply, From, {error, timeout}}]};
@@ -2272,11 +2270,11 @@ cleanup_close_read(P, D, State, Reason) ->
     case State of
         #accept{
            info = SelectInfo, from = From, listen_socket = ListenSocket} ->
-            socket_cancel(ListenSocket, SelectInfo),
+            _ = socket_cancel(ListenSocket, SelectInfo),
             {D,
              [{reply, From, {error, Reason}}]};
         #connect{info = SelectInfo, from = From} ->
-            socket_cancel(P#params.socket, SelectInfo),
+            _ = socket_cancel(P#params.socket, SelectInfo),
             {D,
              [{reply, From, {error, Reason}}]};
         _ ->
@@ -2287,7 +2285,7 @@ cleanup_recv(P, D, State, Reason) ->
     %% ?DBG({P#params.socket, State, Reason}),    
     case State of
         #recv{info = SelectInfo} ->
-            socket_cancel(P#params.socket, SelectInfo),
+            _ = socket_cancel(P#params.socket, SelectInfo),
             cleanup_recv_reply(P, D, [], Reason);
         _ ->
             cleanup_recv_reply(P, D, [], Reason)
diff --git a/lib/kernel/src/socket.erl b/lib/kernel/src/socket.erl
index 4781167c26..02e199d088 100644
--- a/lib/kernel/src/socket.erl
+++ b/lib/kernel/src/socket.erl
@@ -4547,11 +4547,12 @@ ioctl(Socket, SetRequest, Arg1, Arg2) ->
 -spec cancel(Socket, SelectInfo) -> 'ok' | {'error', Reason} when
       Socket         :: socket(),
       SelectInfo     :: select_info(),
-      Reason         :: 'closed' | 'select_sent' | invalid();
+      Reason         :: 'closed' | invalid();
+
             (Socket, CompletionInfo) -> 'ok' | {'error', Reason} when
       Socket         :: socket(),
       CompletionInfo :: completion_info(),
-      Reason         :: 'closed' | 'select_sent' | invalid().
+      Reason         :: 'closed' | invalid().
 
 cancel(?socket(SockRef), ?SELECT_INFO(SelectTag, SelectHandle) = SelectInfo)
   when is_reference(SockRef) ->
@@ -4590,14 +4591,10 @@ cancel(Socket, Info) ->
     erlang:error(badarg, [Socket, Info]).
 
 
-%% What about completion? There is no way to cancel a 
-%% I/O completion "request" once it has been issued.
-%% But we may still have "stuff" in our own queues,
-%% which needs to be cleared out.
 cancel(SockRef, Op, Handle) ->
     case prim_socket:cancel(SockRef, Op, Handle) of
         select_sent ->
-            flush_select_msg(SockRef, Handle),
+            _ = flush_select_msg(SockRef, Handle),
             _ = flush_abort_msg(SockRef, Handle),
             ok;
         not_found ->
@@ -4605,6 +4602,9 @@ cancel(SockRef, Op, Handle) ->
             _ = flush_abort_msg(SockRef, Handle),
             invalid;
         Result ->
+            %% Since we do not actually if we are using
+            %% select or completion here, so flush both...
+            _ = flush_select_msg(SockRef, Handle),
             _ = flush_completion_msg(SockRef, Handle),
             _ = flush_abort_msg(SockRef, Handle),
             Result