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, 112 insertions, 2 deletions

diff --git a/lib/kernel/test/gen_tcp_misc_SUITE.erl b/lib/kernel/test/gen_tcp_misc_SUITE.erl
index ee271fbdfa..ee8bfcceb1 100644
--- a/lib/kernel/test/gen_tcp_misc_SUITE.erl
+++ b/lib/kernel/test/gen_tcp_misc_SUITE.erl
@@ -25,7 +25,7 @@
 -export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, 
 	 init_per_group/2,end_per_group/2, 
 	 controlling_process/1, controlling_process_self/1,
-	 no_accept/1, close_with_pending_output/1,
+	 no_accept/1, close_with_pending_output/1, active_n/1,
 	 data_before_close/1, iter_max_socks/1, get_status/1,
 	 passive_sockets/1, accept_closed_by_other_process/1,
 	 init_per_testcase/2, end_per_testcase/2,
@@ -70,7 +70,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}].
 all() -> 
     [controlling_process, controlling_process_self, no_accept,
      close_with_pending_output, data_before_close,
-     iter_max_socks, passive_sockets,
+     iter_max_socks, passive_sockets, active_n,
      accept_closed_by_other_process, otp_3924, closed_socket,
      shutdown_active, shutdown_passive, shutdown_pending,
      default_options, http_bad_packet, busy_send,
@@ -407,6 +407,114 @@ send_loop(Sock, Data, Left) ->
     ok = gen_tcp:send(Sock, Data),
     send_loop(Sock, Data, Left-1).
 
+%% Test {active,N} option
+active_n(doc) ->
+    ["Verify operation of the {active,N} option."];
+active_n(suite) -> [];
+active_n(Config) when is_list(Config) ->
+    N = 3,
+    LS = ok(gen_tcp:listen(0, [{active,N}])),
+    [{active,N}] = ok(inet:getopts(LS, [active])),
+    ok = inet:setopts(LS, [{active,-N}]),
+    receive
+        {tcp_passive, LS} -> ok
+    after
+        5000 ->
+            exit({error,tcp_passive_failure})
+    end,
+    [{active,false}] = ok(inet:getopts(LS, [active])),
+    ok = inet:setopts(LS, [{active,0}]),
+    receive
+        {tcp_passive, LS} -> ok
+    after
+        5000 ->
+            exit({error,tcp_passive_failure})
+    end,
+    ok = inet:setopts(LS, [{active,32767}]),
+    {error,einval} = inet:setopts(LS, [{active,1}]),
+    {error,einval} = inet:setopts(LS, [{active,-32769}]),
+    ok = inet:setopts(LS, [{active,-32768}]),
+    receive
+        {tcp_passive, LS} -> ok
+    after
+        5000 ->
+            exit({error,tcp_passive_failure})
+    end,
+    [{active,false}] = ok(inet:getopts(LS, [active])),
+    ok = inet:setopts(LS, [{active,N}]),
+    ok = inet:setopts(LS, [{active,true}]),
+    [{active,true}] = ok(inet:getopts(LS, [active])),
+    receive
+        _ -> exit({error,active_n})
+    after
+        0 ->
+            ok
+    end,
+    ok = inet:setopts(LS, [{active,N}]),
+    ok = inet:setopts(LS, [{active,once}]),
+    [{active,once}] = ok(inet:getopts(LS, [active])),
+    receive
+        _ -> exit({error,active_n})
+    after
+        0 ->
+            ok
+    end,
+    {error,einval} = inet:setopts(LS, [{active,32768}]),
+    ok = inet:setopts(LS, [{active,false}]),
+    [{active,false}] = ok(inet:getopts(LS, [active])),
+    Port = ok(inet:port(LS)),
+    C = ok(gen_tcp:connect("localhost", Port, [{active,N}])),
+    [{active,N}] = ok(inet:getopts(C, [active])),
+    S = ok(gen_tcp:accept(LS)),
+    ok = inet:setopts(S, [{active,N}]),
+    [{active,N}] = ok(inet:getopts(S, [active])),
+    repeat(3,
+           fun(I) ->
+                   Msg = "message "++integer_to_list(I),
+                   ok = gen_tcp:send(C, Msg),
+                   receive
+                       {tcp,S,Msg} ->
+                           ok = gen_tcp:send(S, Msg)
+                   after
+                       5000 ->
+                           exit({error,timeout})
+                   end,
+                   receive
+                       {tcp,C,Msg} ->
+                           ok
+                   after
+                       5000 ->
+                           exit({error,timeout})
+                   end
+           end),
+    receive
+        {tcp_passive,S} ->
+            [{active,false}] = ok(inet:getopts(S, [active]))
+    after
+        5000 ->
+            exit({error,tcp_passive})
+    end,
+    receive
+        {tcp_passive,C} ->
+            [{active,false}] = ok(inet:getopts(C, [active]))
+    after
+        5000 ->
+            exit({error,tcp_passive})
+    end,
+    LS2 = ok(gen_tcp:listen(0, [{active,0}])),
+    receive
+        {tcp_passive,LS2} ->
+            [{active,false}] = ok(inet:getopts(LS2, [active]))
+    after
+        5000 ->
+            exit({error,tcp_passive})
+    end,
+    ok = gen_tcp:close(LS2),
+    ok = gen_tcp:close(C),
+    ok = gen_tcp:close(S),
+    ok = gen_tcp:close(LS),
+    ok.
+
 -define(OTP_3924_MAX_DELAY, 100).
 %% Taken out of the blue, but on intra host connections
 %% I expect propagation of a close to be quite fast
@@ -2659,3 +2767,5 @@ oct_aloop(S,X,Times) ->
 	    gen_tcp:close(S),
 	    closed
     end.
+
+ok({ok,V}) -> V.