diff options
Diffstat (limited to 'doc/src/manual/ranch_tcp.asciidoc')
| -rw-r--r-- | doc/src/manual/ranch_tcp.asciidoc | 199 |
1 files changed, 132 insertions, 67 deletions
diff --git a/doc/src/manual/ranch_tcp.asciidoc b/doc/src/manual/ranch_tcp.asciidoc index 6eb7fa3..d01b262 100644 --- a/doc/src/manual/ranch_tcp.asciidoc +++ b/doc/src/manual/ranch_tcp.asciidoc @@ -2,16 +2,19 @@ == Name -ranch_tcp - TCP transport module +ranch_tcp - TCP transport == Description -The `ranch_tcp` module implements a TCP Ranch transport. +The module `ranch_tcp` implements a TCP Ranch transport. -Note that due to bugs in OTP up to at least R16B02, it is -recommended to disable async threads when using the -`sendfile` function of this transport, as it can make -the threads stuck indefinitely. +The function `sendfile` may not work correctly when used +against files stored in a VirtualBox shared folder. + +== Exports + +The module `ranch_tcp` implements the interface defined +by link:man:ranch_transport(3)[ranch_transport(3)]. == Types @@ -20,44 +23,36 @@ the threads stuck indefinitely. [source,erlang] ---- opt() = {backlog, non_neg_integer()} - | {buffer, non_neg_integer()} - | {delay_send, boolean()} - | {dontroute, boolean()} - | {exit_on_close, boolean()} - | {fd, non_neg_integer()} - | {high_msgq_watermark, non_neg_integer()} - | {high_watermark, non_neg_integer()} - | inet - | inet6 - | {ip, inet:ip_address()} - | {ipv6_v6only, boolean()} - | {keepalive, boolean()} - | {linger, {boolean(), non_neg_integer()}} - | {low_msgq_watermark, non_neg_integer()} - | {low_watermark, non_neg_integer()} - | {nodelay, boolean()} - | {port, inet:port_number()} - | {priority, integer()} - | {raw, non_neg_integer(), non_neg_integer(), binary()} - | {recbuf, non_neg_integer()} - | {send_timeout, timeout()} - | {send_timeout_close, boolean()} - | {sndbuf, non_neg_integer()} - | {tos, integer()} + | {buffer, non_neg_integer()} + | {delay_send, boolean()} + | {dontroute, boolean()} + | {exit_on_close, boolean()} + | {fd, non_neg_integer()} + | {high_msgq_watermark, non_neg_integer()} + | {high_watermark, non_neg_integer()} + | inet + | inet6 + | {ip, inet:ip_address()} + | {ipv6_v6only, boolean()} + | {keepalive, boolean()} + | {linger, {boolean(), non_neg_integer()}} + | {low_msgq_watermark, non_neg_integer()} + | {low_watermark, non_neg_integer()} + | {nodelay, boolean()} + | {port, inet:port_number()} + | {priority, integer()} + | {raw, non_neg_integer(), non_neg_integer(), binary()} + | {recbuf, non_neg_integer()} + | {send_timeout, timeout()} + | {send_timeout_close, boolean()} + | {sndbuf, non_neg_integer()} + | {tos, integer()} ---- Listen options. -This does not represent the entirety of the options that can -be set on the socket, but only the options that may be -set independently of protocol implementation. - -=== opts() = [opt()] - -List of listen options. - -Option descriptions -------------------- +Note that additional options may be set by the protocol +module using `Transport:setopts/2`. None of the options are required. @@ -65,62 +60,132 @@ Please consult the `gen_tcp` and `inet` manuals for a more thorough description of these options. This manual only aims to provide a short description along with what the defaults are. Defaults may be different in Ranch compared to `gen_tcp`. -Defaults are given next to the option name. +Defaults are given next to the option name: backlog (1024):: - Max length of the queue of pending connections. + +Max length of the queue of pending connections. + buffer:: - Size of the buffer used by the Erlang driver. Default is system-dependent. + +Size of the buffer used by the Erlang driver. Default +is system-dependent. + delay_send (false):: - Always queue packets before sending, to send fewer, larger packets over the network. + +Always queue data before sending, to send fewer, larger +packets over the network. + dontroute (false):: - Don't send via a gateway, only send to directly connected hosts. + +Don't send via a gateway, only send to directly connected hosts. + exit_on_close (true):: - Disable to allow sending data after a close has been detected. + +Disable to allow sending data after a close has been detected. + fd:: - File descriptor of the socket, if it was opened externally. + +File descriptor of the socket, if it was opened externally. + high_msgq_watermark (8192):: - Limit in the amount of data in the socket message queue before the socket queue becomes busy. + +Limit in the amount of data in the socket message queue before +the queue becomes busy. + high_watermark (8192):: - Limit in the amount of data in the ERTS socket implementation's queue before the socket becomes busy. + +Limit in the amount of data in the ERTS socket implementation's +queue before the socket becomes busy. + inet:: - Set up the socket for IPv4. + +Set up the socket for IPv4. + inet6:: - Set up the socket for IPv6. + +Set up the socket for IPv6. + ip:: - Interface to listen on. Listen on all interfaces by default. + +Interface to listen on. Listen on all interfaces by default. + ipv6_v6only (false):: - Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6. + +Listen on IPv4 and IPv6 (false) or only on IPv6 (true). +Use with inet6. + keepalive (false):: - Enable sending of keep-alive messages. + +Enable sending of keep-alive messages. + linger ({false, 0}):: - Whether to wait and how long to flush data sent before closing the socket. + +Whether to wait and how long to flush data sent before closing +the socket. + low_msgq_watermark (4096):: - Amount of data in the socket message queue before the socket queue leaves busy state. + +Amount of data in the socket message queue before the queue +leaves busy state. + low_watermark (4096):: - Amount of data in the ERTS socket implementation's queue before the socket leaves busy state. + +Amount of data in the ERTS socket implementation's queue +before the socket leaves busy state. + nodelay (true):: - Whether to enable TCP_NODELAY. + +Whether to enable TCP_NODELAY. + port (0):: - TCP port number to listen on. 0 means a random port will be used. + +TCP port number to listen on. 0 means a random port will be used. + priority (0):: - Priority value for all packets to be sent by this socket. + +Priority value for all packets to be sent on this socket. + recbuf:: - Minimum size of the socket's receive buffer. Default is system-dependent. + +Minimum size of the socket's receive buffer. +Default is system-dependent. + send_timeout (30000):: - How long the send call may wait for confirmation before returning. + +How long the send call may wait for confirmation before returning. + send_timeout_close (true):: - Whether to close the socket when the confirmation wasn't received. + +Whether to close the socket when the confirmation wasn't received. + sndbuf:: - Minimum size of the socket's send buffer. Default is system-dependent. + +Minimum size of the socket's send buffer. +Default is system-dependent. + tos:: - Value for the IP_TOS IP level option. Use with caution. + +Value for the IP_TOS IP level option. Use with caution. In addition, the `raw` option can be used to set system-specific options by specifying the protocol level, the option number and the actual option value specified as a binary. This option is not portable. Use with caution. -== Exports +=== opts() + +[source,erlang] +---- +opts() :: [opt()] +---- + +List of listen options. + +== See also -None. +link:man:ranch(7)[ranch(7)], +link:man:ranch_transport(3)[ranch_transport(3)], +link:man:ranch_ssl(3)[ranch_ssl(3)], +gen_tcp(3), +inet(3) |