[esock|doc] Add documentation for the (socket) info function

Add documentation for the (socket) info function, which (among
other things) return the socket counters. Also typed the
return value (socket_info()).

OTP-15818

3 files changed, 37 insertions, 1 deletions

diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml
index b4e22e86a8..da049b1a7f 100644
--- a/erts/doc/src/socket.xml
+++ b/erts/doc/src/socket.xml
@@ -112,6 +112,15 @@
       <name name="select_info"/>
     </datatype>
     <datatype>
+      <name name="socket_counters"/>
+    </datatype>
+    <datatype>
+      <name name="socket_counter"/>
+    </datatype>
+    <datatype>
+      <name name="socket_info"/>
+    </datatype>
+    <datatype>
       <name name="ip4_address"/>
     </datatype>
     <datatype>
@@ -456,6 +465,20 @@
     </func>
 
     <func>
+      <name name="info" arity="1" since="OTP @OTP-15818@"/>
+      <fsummary>Get miscellaneous socket info.</fsummary>
+      <desc>
+        <p>Get miscellaneous info about the socket.</p>
+	<p>The function returns a map with each info item as a key-value
+	binding. It reflects the "current" state of the socket. </p>
+	<note>
+	  <p>In order to ensure data integrity, mutex'es are taken when
+	  needed. So, do not call this function often. </p>
+	</note>
+      </desc>
+    </func>
+
+    <func>
       <name name="listen" arity="1" since="OTP 22.0"/>
       <name name="listen" arity="2" since="OTP 22.0"/>
       <fsummary>Listen for connections on a socket.</fsummary>
diff --git a/erts/preloaded/ebin/socket.beam b/erts/preloaded/ebin/socket.beam
index 42959cac4b..25eb0b2f4a 100644
--- a/erts/preloaded/ebin/socket.beam
+++ b/erts/preloaded/ebin/socket.beam
diff --git a/erts/preloaded/src/socket.erl b/erts/preloaded/src/socket.erl
index b0f84700a1..be94e3a867 100644
--- a/erts/preloaded/src/socket.erl
+++ b/erts/preloaded/src/socket.erl
@@ -67,6 +67,10 @@
               select_ref/0,
               select_info/0,
 
+              socket_counters/0,
+              socket_counter/0,
+              socket_info/0,
+
               %% command/0,
 
               domain/0,
@@ -153,6 +157,15 @@
                           }.
 %% -type command() :: debug_command().
 
+-type socket_counters() :: [{socket_counter(), non_neg_integer()}].
+-type socket_counter()  :: read_byte | read_fails | read_pkg | read_tries |
+                           read_waits | write_byte | write_fails | write_pkg |
+                           write_tries | write_waits.
+-type socket_info() :: #{counters      := socket_counters(),
+                         num_readers   := non_neg_integer(),
+                         num_writers   := non_neg_integer(),
+                         num_acceptors := non_neg_integer()}.
+
 -type uint8()  :: 0..16#FF.
 -type uint16() :: 0..16#FFFF.
 -type uint20() :: 0..16#FFFFF.
@@ -912,7 +925,7 @@ command(#{command := debug,
 %% 
 %% ===========================================================================
 
--spec info(Socket) -> map() when
+-spec info(Socket) -> socket_info() when
       Socket :: socket().
 
 info(#socket{ref = SockRef}) ->