aboutsummaryrefslogblamecommitdiffstats
path: root/manual/ranch_tcp.md
blob: c274b0bab3e3c32465957260b90c62214c53272e (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12
13












                                                         
                                        








                                                  
                                 
                                
                                                  

                                                 

                                    


                                                               
                                   
                                         

                                     



                                                              
                                                        

                                               

                    
                         
 




                                 




                                                              


                                                     

















                                                                                                           

                                                                  

                                            

                                                                                



                                                                                                   



                                                                       



                                                                               



                                                                        



                                                                            
 



                                                                 




       
ranch_tcp
=========

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() = {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.