aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc
diff options
context:
space:
mode:
authorSteve Vinoski <[email protected]>2013-08-27 11:42:00 -0400
committerLukas Larsson <[email protected]>2013-09-23 17:23:14 +0200
commit7fbf2c26ac063988818230a0e18a9df48c2fbf2d (patch)
tree8ee574a718eb61d7d99133e47a2a37bc1d94e115 /lib/kernel/doc
parentcc3c34fce28062afcaadc288b69939ced8fd8cde (diff)
downloadotp-7fbf2c26ac063988818230a0e18a9df48c2fbf2d.tar.gz
otp-7fbf2c26ac063988818230a0e18a9df48c2fbf2d.tar.bz2
otp-7fbf2c26ac063988818230a0e18a9df48c2fbf2d.zip
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.
Diffstat (limited to 'lib/kernel/doc')
-rw-r--r--lib/kernel/doc/src/gen_sctp.xml31
-rw-r--r--lib/kernel/doc/src/gen_tcp.xml6
-rw-r--r--lib/kernel/doc/src/gen_udp.xml17
-rw-r--r--lib/kernel/doc/src/inet.xml51
4 files changed, 79 insertions, 26 deletions
diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml
index dacea7a239..986260638d 100644
--- a/lib/kernel/doc/src/gen_sctp.xml
+++ b/lib/kernel/doc/src/gen_sctp.xml
@@ -496,9 +496,11 @@
orthogonal to the sets of TCP, UDP and generic INET options:
only those options which are explicitly listed below are allowed
for SCTP sockets. Options can be set on the socket using
- <c>gen_sctp:open/1,2</c> or <c>inet:setopts/2</c>,
- retrieved using <c>inet:getopts/2</c>, and when calling
- <c>gen_sctp:connect/4,5</c> options can be changed.</p>
+ <seealso marker="#open/1"><c>gen_sctp:open/1,2</c></seealso>
+ or <seealso marker="inet#setopts/2"><c>inet:setopts/2</c></seealso>,
+ retrieved using <seealso marker="inet#getopts/2"><c>inet:getopts/2</c></seealso>,
+ and when calling <seealso marker="#connect/4"><c>gen_sctp:connect/4,5</c></seealso>
+ options can be changed.</p>
<marker id="option-binary"></marker>
<marker id="option-list"></marker>
<taglist>
@@ -507,7 +509,7 @@
<p>Determines the type of data returned from <c>gen_sctp:recv/1,2</c>.</p>
<marker id="option-active"></marker>
</item>
- <tag><c>{active, true|false|once}</c></tag>
+ <tag><c>{active, true|false|once|N}</c></tag>
<item>
<list type="bulleted">
<item>
@@ -524,11 +526,28 @@
</item>
<item>
<p>If <c>once</c>, only one message is automatically placed
- in the message queue, after that the mode is automatically
- re-set to passive. This provides flow control as well as
+ in the message queue, and after that the mode is automatically
+ reset to passive. This provides flow control as well as
the possibility for the receiver to listen for its incoming
SCTP data interleaved with other inter-process messages.</p>
</item>
+ <item>
+ <p>If <c>active</c> is specified as an integer <c>N</c> in the
+ range -32768 to 32767 (inclusive), then that number is added to
+ the socket's count of the number of data messages to be
+ delivered to the controlling process. If the result of the
+ addition would be negative, the count is set to 0. Once the
+ count reaches 0, either through the delivery of messages or by
+ being explicitly set with <seealso
+ marker="inet#setopts/2">inet:setopts/2</seealso>, the socket's
+ mode is automatically reset to passive (<c>{active,
+ false}</c>) mode. When a socket in this active mode transitions to
+ passive mode, the message <c>{sctp_passive, Socket}</c> is sent
+ to the controlling process to notify it that if it wants to
+ receive more data messages from the socket, it must call
+ <seealso marker="inet#setopts/2">inet:setopts/2</seealso> to set
+ the socket back into an active mode.</p>
+ </item>
</list>
</item>
<tag><c>{tos, integer()}</c></tag>
diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index 7afd73f4bf..dbd0d3c815 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -148,6 +148,12 @@ do_recv(Sock, Bs) ->
as messages:</p>
<code type="none">
{tcp, Socket, Data}</code>
+ <p>If the socket is in <c>{active, N}</c> mode (see <seealso marker="inet#setopts/2">
+ inet:setopts/2</seealso> for details) and its message counter
+ drops to 0, the following message is delivered to indicate that the
+ socket has transitioned to passive (<c>{active, false}</c>) mode:</p>
+ <code type="none">
+{tcp_passive, Socket}</code>
<p>If the socket is closed, the following message is delivered:</p>
<code type="none">
{tcp_closed, Socket}</code>
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index faca31e928..503725fe18 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -145,14 +145,23 @@
<seealso marker="inet#setopts/2">inet:setopts/2</seealso>.</p>
</item>
</taglist>
- <p>The returned socket <c><anno>Socket</anno></c> is used to send packets
- from this port with <c>send/4</c>. When UDP packets arrive at
- the opened port, they are delivered as messages:</p>
+ <p>The returned socket <c><anno>Socket</anno></c> is used to send
+ packets from this port with <c>send/4</c>. When UDP packets arrive
+ at the opened port, if the socket is in an active mode the packets
+ are delivered as messages to the controlling process:</p>
<code type="none">
{udp, Socket, IP, InPortNo, Packet}</code>
- <p>Note that arriving UDP packets that are longer than
+ <p>If the socket is not in an active mode, data can be
+ retrieved via the <seealso marker="#recv/2">recv/2,3</seealso> calls.
+ Note that arriving UDP packets that are longer than
the receive buffer option specifies, might be truncated
without warning.</p>
+ <p>When a socket in <c>{active, N}</c> mode (see <seealso marker="inet#setopts/2">
+ inet:setopts/2</seealso> for details) transitions to passive
+ (<c>{active, false}</c>) mode, the controlling process is notified by a
+ message of the following form:</p>
+ <code type="none">
+{udp_passive, Socket}</code>
<p><c>IP</c> and <c>InPortNo</c> define the address from which
<c>Packet</c> came. <c>Packet</c> is a list of bytes if
the option <c>list</c> was specified. <c>Packet</c> is a
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index e1b0b34888..fb8bf32978 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -456,47 +456,66 @@ fe80::204:acff:fe17:bf38
<p>Sets one or more options for a socket. The following options
are available:</p>
<taglist>
- <tag><c>{active, true | false | once}</c></tag>
+ <tag><c>{active, true | false | once | N}</c></tag>
<item>
<p>If the value is <c>true</c>, which is the default,
everything received from the socket will be sent as
messages to the receiving process. If the value is
<c>false</c> (passive mode), the process must explicitly
- receive incoming data by calling <c>gen_tcp:recv/2,3</c>
- or <c>gen_udp:recv/2,3</c> (depending on the type of
- socket).</p>
+ receive incoming data by calling
+ <seealso marker="gen_tcp#recv/2"><c>gen_tcp:recv/2,3</c></seealso>,
+ <seealso marker="gen_udp#recv/2"><c>gen_udp:recv/2,3</c></seealso>
+ or <seealso marker="gen_sctp#recv/1"><c>gen_sctp:recv/1,2</c></seealso>
+ (depending on the type of socket).</p>
<p>If the value is <c>once</c> (<c>{active, once}</c>),
<em>one</em> data message from the socket will be sent
to the process. To receive one more message,
<c>setopts/2</c> must be called again with the
<c>{active, once}</c> option.</p>
- <p>When using <c>{active, once}</c>, the socket changes
- behaviour automatically when data is received. This can
- sometimes be confusing in combination with connection
- oriented sockets (i.e. <c>gen_tcp</c>) as a socket with
- <c>{active, false}</c> behaviour reports closing
+ <p>If the value is an integer <c>N</c> in the range -32768 to 32767
+ (inclusive), the value is added to the socket's count of data
+ messages sent to the controlling process. A socket's default
+ message count is 0. If a negative value is specified and its
+ magnitude is equal to or greater than the socket's current
+ message count, the socket's message count is set to 0. Once
+ the socket's message count reaches 0, either due to sending
+ received data messages to the process or by being explicitly set,
+ the process is then notified by a special message, specific to
+ the type of socket, that the socket has entered passive
+ mode. Once the socket enters passive mode, to receive more
+ messages <c>setopts/2</c> must be called again to set the
+ socket back into an active mode.</p>
+ <p>When using <c>{active, once}</c> or <c>{active, N}</c>, the
+ socket changes behaviour automatically when data is received.
+ This can sometimes be confusing in combination with
+ connection-oriented sockets (i.e. <c>gen_tcp</c>) as a socket
+ with <c>{active, false}</c> behaviour reports closing
differently than a socket with <c>{active, true}</c>
behaviour. To make programming easier, a socket where
the peer closed and this was detected while in
<c>{active, false}</c> mode, will still generate the
message
- <c>{tcp_closed,Socket}</c> when set to <c>{active, once}</c> or <c>{active, true}</c> mode. It is therefore
+ <c>{tcp_closed,Socket}</c> when set to <c>{active, once}</c>,
+ <c>{active, true}</c> or <c>{active, N}</c> mode. It is therefore
safe to assume that the message
<c>{tcp_closed,Socket}</c>, possibly followed by socket
port termination (depending on the <c>exit_on_close</c>
option) will eventually appear when a socket changes
back and forth between <c>{active, true}</c> and
- <c>{active, false}</c> mode. However,
+ <c>{active, false}</c> mode. However,
<em>when</em> peer closing is detected is all up to the
underlying TCP/IP stack and protocol.</p>
- <p>Note that <c>{active,true}</c> mode provides no flow
+ <p>Note that <c>{active, true}</c> mode provides no flow
control; a fast sender could easily overflow the
- receiver with incoming messages. Use active mode only if
+ receiver with incoming messages. The same is true of
+ <c>{active, N}</c> mode while the message count is greater
+ than zero. Use active mode only if
your high-level protocol provides its own flow control
(for instance, acknowledging received messages) or the
- amount of data exchanged is small. <c>{active,false}</c>
- mode or use of the <c>{active, once}</c> mode provides
- flow control; the other side will not be able send
+ amount of data exchanged is small. <c>{active, false}</c>
+ mode, use of the <c>{active, once}</c> mode or <c>{active, N}</c>
+ mode with values of <c>N</c> appropriate for the application
+ provides flow control; the other side will not be able send
faster than the receiver can read.</p>
</item>