aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/ranch_tcp.asciidoc
blob: 1fc268d8f594f723fb002f96a12f19bf44a2740c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
= ranch_tcp(3)

== Name

ranch_tcp - TCP transport module

== Description

The `ranch_tcp` module 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.

== Types

=== opt()

[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()}
	| {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
-------------------

None of the options are required.

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.

backlog (1024)::
	Max length of the queue of pending connections.
buffer::
	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.
dontroute (false)::
	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.
fd::
	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.
high_watermark (8192)::
	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.
inet6::
	Set up the socket for IPv6.
ip::
	Interface to listen on. Listen on all interfaces by default.
keepalive (false)::
	Enable sending of keep-alive messages.
linger ({false, 0})::
	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.
low_watermark (4096)::
	Amount of data in the ERTS socket implementation's queue before the socket leaves busy state.
nodelay (true)::
	Whether to enable TCP_NODELAY.
port (0)::
	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.
recbuf::
	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.
send_timeout_close (true)::
	Whether to close the socket when the confirmation wasn't received.
sndbuf::
	Minimum size of the socket's send buffer. Default is system-dependent.
tos::
	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

None.