add {active,N} socket option for TCP, UDP, and SCTP

Add the {active,N} socket option, where N is an integer in the range
-32768..32767, to allow a caller to specify the number of data messages to
be delivered to the controlling process. Once the socket's delivered
message count either reaches 0 or is explicitly set to 0 with
inet:setopts/2 or by including {active,0} as an option when the socket is
created, the socket transitions to passive ({active, false}) mode and the
socket's controlling process receives a message to inform it of the
transition. TCP sockets receive {tcp_passive,Socket}, UDP sockets receive
{udp_passive,Socket} and SCTP sockets receive {sctp_passive,Socket}.

The socket's delivered message counter defaults to 0, but it can be set
using {active,N} via any gen_tcp, gen_udp, or gen_sctp function that takes
socket options as arguments, or via inet:setopts/2. New N values are added
to the socket's current counter value, and negative numbers can be used to
reduce the counter value. Specifying a number that would cause the socket's
counter value to go above 32767 causes an einval error. If a negative
number is specified such that the counter value would become negative, the
socket's counter value is set to 0 and the socket transitions to passive
mode. If the counter value is already 0 and inet:setopts(Socket,
[{active,0}]) is specified, the counter value remains at 0 but the
appropriate passive mode transition message is generated for the socket.

This commit contains a modified preloaded prim_inet.beam due to changes in
prim_inet.erl.

Add tests for {active,N} mode for TCP, UDP, and SCTP sockets.

Add documentation for {active,N} mode for inet, gen_tcp, gen_udp, and
gen_sctp.

1 files changed, 104 insertions, 2 deletions

diff --git a/lib/kernel/test/gen_udp_SUITE.erl b/lib/kernel/test/gen_udp_SUITE.erl
index 4cc6018614..6bb41999c5 100644
--- a/lib/kernel/test/gen_udp_SUITE.erl
+++ b/lib/kernel/test/gen_udp_SUITE.erl
@@ -33,7 +33,7 @@
 	 init_per_group/2,end_per_group/2]).
 -export([init_per_testcase/2, end_per_testcase/2]).
 
--export([send_to_closed/1, 
+-export([send_to_closed/1, active_n/1,
 	 buffer_size/1, binary_passive_recv/1, bad_address/1,
 	 read_packets/1, open_fd/1, connect/1, implicit_inet6/1]).
 
@@ -42,7 +42,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}].
 all() -> 
     [send_to_closed, buffer_size, binary_passive_recv,
      bad_address, read_packets, open_fd, connect,
-     implicit_inet6].
+     implicit_inet6, active_n].
 
 groups() -> 
     [].
@@ -465,6 +465,108 @@ open_fd(Config) when is_list(Config) ->
 	    ?t:fail(io_lib:format("~w", [flush()]))
     end.
 
+active_n(Config) when is_list(Config) ->
+    N = 3,
+    S1 = ok(gen_udp:open(0, [{active,N}])),
+    [{active,N}] = ok(inet:getopts(S1, [active])),
+    ok = inet:setopts(S1, [{active,-N}]),
+    receive
+        {udp_passive, S1} -> ok
+    after
+        5000 ->
+            exit({error,udp_passive_failure})
+    end,
+    [{active,false}] = ok(inet:getopts(S1, [active])),
+    ok = inet:setopts(S1, [{active,0}]),
+    receive
+        {udp_passive, S1} -> ok
+    after
+        5000 ->
+            exit({error,udp_passive_failure})
+    end,
+    ok = inet:setopts(S1, [{active,32767}]),
+    {error,einval} = inet:setopts(S1, [{active,1}]),
+    {error,einval} = inet:setopts(S1, [{active,-32769}]),
+    ok = inet:setopts(S1, [{active,-32768}]),
+    receive
+        {udp_passive, S1} -> ok
+    after
+        5000 ->
+            exit({error,udp_passive_failure})
+    end,
+    [{active,false}] = ok(inet:getopts(S1, [active])),
+    ok = inet:setopts(S1, [{active,N}]),
+    ok = inet:setopts(S1, [{active,true}]),
+    [{active,true}] = ok(inet:getopts(S1, [active])),
+    receive
+        _ -> exit({error,active_n})
+    after
+        0 ->
+            ok
+    end,
+    ok = inet:setopts(S1, [{active,N}]),
+    ok = inet:setopts(S1, [{active,once}]),
+    [{active,once}] = ok(inet:getopts(S1, [active])),
+    receive
+        _ -> exit({error,active_n})
+    after
+        0 ->
+            ok
+    end,
+    {error,einval} = inet:setopts(S1, [{active,32768}]),
+    ok = inet:setopts(S1, [{active,false}]),
+    [{active,false}] = ok(inet:getopts(S1, [active])),
+    S1Port = ok(inet:port(S1)),
+    S2 = ok(gen_udp:open(0, [{active,N}])),
+    S2Port = ok(inet:port(S2)),
+    [{active,N}] = ok(inet:getopts(S2, [active])),
+    ok = inet:setopts(S1, [{active,N}]),
+    [{active,N}] = ok(inet:getopts(S1, [active])),
+    lists:foreach(
+      fun(I) ->
+              Msg = "message "++integer_to_list(I),
+              ok = gen_udp:send(S2, "localhost", S1Port, Msg),
+              receive
+                  {udp,S1,_,S2Port,Msg} ->
+                      ok = gen_udp:send(S1, "localhost", S2Port, Msg)
+              after
+                  5000 ->
+                      exit({error,timeout})
+              end,
+              receive
+                  {udp,S2,_,S1Port,Msg} ->
+                      ok
+              after
+                  5000 ->
+                      exit({error,timeout})
+              end
+      end, lists:seq(1,N)),
+    receive
+        {udp_passive,S1} ->
+            [{active,false}] = ok(inet:getopts(S1, [active]))
+    after
+        5000 ->
+            exit({error,udp_passive})
+    end,
+    receive
+        {udp_passive,S2} ->
+            [{active,false}] = ok(inet:getopts(S2, [active]))
+    after
+        5000 ->
+            exit({error,udp_passive})
+    end,
+    S3 = ok(gen_udp:open(0, [{active,0}])),
+    receive
+        {udp_passive,S3} ->
+            [{active,false}] = ok(inet:getopts(S3, [active]))
+    after
+        5000 ->
+            exit({error,udp_passive})
+    end,
+    ok = gen_udp:close(S3),
+    ok = gen_udp:close(S2),
+    ok = gen_udp:close(S1),
+    ok.
 
 %
 % Utils