diff options
Diffstat (limited to 'manual/ranch.md')
| -rw-r--r-- | manual/ranch.md | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/manual/ranch.md b/manual/ranch.md deleted file mode 100644 index 52c792e..0000000 --- a/manual/ranch.md +++ /dev/null @@ -1,182 +0,0 @@ -ranch -===== - -The `ranch` module provides functions for starting and -manipulating Ranch listeners. - -Types ------ - -### max_conns() = non_neg_integer() | infinity - -> Maximum number of connections allowed on this listener. -> -> This is a soft limit. The actual number of connections -> might be slightly above the limit due to concurrency -> when accepting new connections. Some connections may -> also be removed from this count explicitly by the user -> code. - -### opt() = {ack_timeout, timeout()} - | {connection_type, worker | supervisor} - | {max_connections, max_conns()} - | {shutdown, timeout() | brutal_kill} - | {socket, any()} - -> Ranch-specific transport options. -> -> These options are not passed on to the transports. -> They are used by Ranch while setting up the listeners. - -### ref() = any() - -> Unique name used to refer to a listener. - -Exports -------- - -### accept_ack(Ref) -> ok - -> Types: -> * Ref = ref() -> -> Acknowledge that the connection is accepted. -> -> This function MUST be used by a connection process to inform -> Ranch that it initialized properly and let it perform any -> additional operations before the socket can be safely used. - -### child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) - -> supervisor:child_spec() - -> Types: -> * Ref = ref() -> * NbAcceptors = non_neg_integer() -> * Transport = module() -> * TransOpts = any() -> * Protocol = module() -> * ProtoOpts = any() -> -> Return child specifications for a new listener. -> -> This function can be used to embed a listener directly -> in an application instead of letting Ranch handle it. - -### get_max_connections(Ref) -> MaxConns - -> Types: -> * Ref = ref() -> * MaxConns = max_conns() -> -> Return the max number of connections allowed for the given listener. - -### get_port(Ref) -> Port - -> Types: -> * Ref = ref() -> * Port = inet:port_number() -> -> Return the port for the given listener. - -### get_protocol_options(Ref) -> ProtoOpts - -> Types: -> * Ref = ref() -> * ProtoOpts = any() -> -> Return the protocol options set for the given listener. - -### remove_connection(Ref) -> ok - -> Types: -> * Ref = ref() -> -> Do not count this connection when limiting the number of connections. -> -> You can use this function for long-running connection processes -> which spend most of their time idling rather than consuming -> resources. This allows Ranch to accept a lot more connections -> without sacrificing the latency of the system. -> -> This function may only be called from a connection process. - -### set_max_connections(Ref, MaxConns) -> ok - -> Types: -> * Ref = ref() -> * MaxConns = max_conns() -> -> Set the max number of connections for the given listener. -> -> The change will be applied immediately. If the new value is -> smaller than the previous one, Ranch will not kill the extra -> connections, but will wait for them to terminate properly. - -### set_protocol_options(Ref, ProtoOpts) -> ok - -> Types: -> * Ref = ref() -> * ProtoOpts = any() -> -> Set the protocol options for the given listener. -> -> The change will be applied immediately for all new connections. -> Old connections will not receive the new options. - -### start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) - -> {ok, pid()} | {error, badarg} - -> Types: -> * Ref = ref() -> * NbAcceptors = non_neg_integer() -> * Transport = module() -> * TransOpts = any() -> * Protocol = module() -> * ProtoOpts = any() -> -> Start listening for connections using the given transport -> and protocol. Returns the pid for this listener's supervisor. -> -> There are five additional transport options that apply -> regardless of transport. They allow configuring how the -> connections are supervised, rate limited and allow using -> an already open listening socket. -> -> The `ack_timeout` option defines how long post-accept socket -> initialization should take at a maximum. It defaults to `5000`. -> -> The `connection_type` option defines the type of process -> that will handle the connection. It can be either `worker` -> or `supervisor`. It defaults to `worker`. -> -> The `max_connections` option determines how many active -> connections are allowed before Ranch starts throttling -> the accept rate. This is a soft limit. It defaults to `1024`. -> Using the value `infinity` will disable this functionality -> entirely. -> -> The `shutdown` option determines the policy used with -> regards to connection processes when shutting down the listener. -> It can be either a positive integer indicating the max number -> of ms the supervisor will wait before forcibly killing the -> children, or the atom `brutal_kill`. It defaults to `5000`. -> -> The `socket` option allow passing an already open listening -> socket. In this case, Ranch will not call `Transport:listen/1` -> and so none of the transport specific options apply. - -### stop_listener(Ref) -> ok | {error, not_found} - -> Types: -> * Ref = ref() -> -> Stop the given listener. -> -> The listener is stopped gracefully, first by closing the -> listening port, then by stopping the connection processes. -> These processes are stopped according to the `shutdown` -> transport option, which may be set to brutally kill all -> connection processes or give them some time to stop properly. -> -> This function does not return until the listener is -> completely stopped. |