From 8b4c6f4bf9880d59bbc012b6ba9d5e60c4f62b3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 18 Jul 2018 17:24:41 +0200 Subject: Add one manual per function for the ranch module Also review and update the ranch(7) manual and fix a few specs. --- doc/src/guide/upcoming_2.0_changes.asciidoc | 4 + doc/src/manual/ranch.asciidoc | 304 +++++---------------- doc/src/manual/ranch.child_spec.asciidoc | 103 +++++++ doc/src/manual/ranch.get_addr.asciidoc | 44 +++ doc/src/manual/ranch.get_max_connections.asciidoc | 40 +++ doc/src/manual/ranch.get_port.asciidoc | 44 +++ doc/src/manual/ranch.get_protocol_options.asciidoc | 40 +++ doc/src/manual/ranch.get_status.asciidoc | 46 ++++ .../manual/ranch.get_transport_options.asciidoc | 40 +++ doc/src/manual/ranch.handshake.asciidoc | 74 +++++ doc/src/manual/ranch.info.asciidoc | 65 +++++ doc/src/manual/ranch.procs.asciidoc | 51 ++++ doc/src/manual/ranch.remove_connection.asciidoc | 46 ++++ doc/src/manual/ranch.resume_listener.asciidoc | 57 ++++ doc/src/manual/ranch.set_max_connections.asciidoc | 50 ++++ doc/src/manual/ranch.set_protocol_options.asciidoc | 48 ++++ .../manual/ranch.set_transport_options.asciidoc | 56 ++++ doc/src/manual/ranch.start_listener.asciidoc | 131 +++++++++ doc/src/manual/ranch.stop_listener.asciidoc | 58 ++++ doc/src/manual/ranch.suspend_listener.asciidoc | 62 +++++ doc/src/manual/ranch.wait_for_connections.asciidoc | 76 ++++++ doc/src/manual/ranch_app.asciidoc | 45 ++- 22 files changed, 1238 insertions(+), 246 deletions(-) create mode 100644 doc/src/manual/ranch.child_spec.asciidoc create mode 100644 doc/src/manual/ranch.get_addr.asciidoc create mode 100644 doc/src/manual/ranch.get_max_connections.asciidoc create mode 100644 doc/src/manual/ranch.get_port.asciidoc create mode 100644 doc/src/manual/ranch.get_protocol_options.asciidoc create mode 100644 doc/src/manual/ranch.get_status.asciidoc create mode 100644 doc/src/manual/ranch.get_transport_options.asciidoc create mode 100644 doc/src/manual/ranch.handshake.asciidoc create mode 100644 doc/src/manual/ranch.info.asciidoc create mode 100644 doc/src/manual/ranch.procs.asciidoc create mode 100644 doc/src/manual/ranch.remove_connection.asciidoc create mode 100644 doc/src/manual/ranch.resume_listener.asciidoc create mode 100644 doc/src/manual/ranch.set_max_connections.asciidoc create mode 100644 doc/src/manual/ranch.set_protocol_options.asciidoc create mode 100644 doc/src/manual/ranch.set_transport_options.asciidoc create mode 100644 doc/src/manual/ranch.start_listener.asciidoc create mode 100644 doc/src/manual/ranch.stop_listener.asciidoc create mode 100644 doc/src/manual/ranch.suspend_listener.asciidoc create mode 100644 doc/src/manual/ranch.wait_for_connections.asciidoc (limited to 'doc') diff --git a/doc/src/guide/upcoming_2.0_changes.asciidoc b/doc/src/guide/upcoming_2.0_changes.asciidoc index 40fc4e9..f60bde6 100644 --- a/doc/src/guide/upcoming_2.0_changes.asciidoc +++ b/doc/src/guide/upcoming_2.0_changes.asciidoc @@ -14,6 +14,10 @@ recent Ranch version. * The function `ranch:accept_ack/1` has been deprecated in favor of `ranch:handshake/1,2`. +* The function `ranch:info/1,2` will return a map containing + each listener's information rather than a list of key/values. + The `num_acceptors` key will be removed. + * The socket will no longer be passed to the protocol when starting it. It will be available as a return value from `ranch:handshake/1,2` only. diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc index 247558d..f2cbb41 100644 --- a/doc/src/manual/ranch.asciidoc +++ b/doc/src/manual/ranch.asciidoc @@ -2,16 +2,58 @@ == Name -ranch - socket acceptor pool +ranch - Socket acceptor pool == Description -The `ranch` module provides functions for starting and +The module `ranch` provides functions for starting and manipulating Ranch listeners. +== Exports + +Start/stop: + +* link:man:ranch:start_listener(3)[ranch:start_listener(3)] - Start a listener +* link:man:ranch:stop_listener(3)[ranch:stop_listener(3)] - Stop a listener +* link:man:ranch:child_spec(3)[ranch:child_spec(3)] - Build child specifications for a new listener + +Suspend/resume: + +* link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)] - Suspend a running listener +* link:man:ranch:resume_listener(3)[ranch:resume_listener(3)] - Resume a suspended listener +* link:man:ranch:get_status(3)[ranch:get_status(3)] - Get a listener's running state + +Connections: + +* ranch:accept_ack(3) - Deprecated in favor of link:man:ranch:handshake(3)[ranch:handshake(3)] +* link:man:ranch:handshake(3)[ranch:handshake(3)] - Perform the transport handshake +* link:man:ranch:remove_connection(3)[ranch:remove_connection(3)] - Remove connection from the count + +Options: + +* link:man:ranch:get_max_connections(3)[ranch:get_max_connections(3)] - Get the max number of connections +* link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)] - Get the current protocol options +* link:man:ranch:get_transport_options(3)[ranch:get_transport_options(3)] - Get the current transport options +* link:man:ranch:set_max_connections(3)[ranch:set_max_connections(3)] - Set the max number of connections +* link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)] - Set the protocol options +* link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)] - Set the transport options + +Introspection: + +* link:man:ranch:get_addr(3)[ranch:get_addr(3)] - Get the listening port and IP +* link:man:ranch:get_port(3)[ranch:get_port(3)] - Get the listening port +* link:man:ranch:info(3)[ranch:info(3)] - Overview of Ranch listeners +* link:man:ranch:procs(3)[ranch:procs(3)] - Retrieve pids from a listener +* link:man:ranch:wait_for_connections(3)[ranch:wait_for_connections(3)] - Wait for a specific number of connections + == Types -=== max_conns() = non_neg_integer() | infinity +=== max_conns() + +[source,erlang] +---- +max_conns() = non_neg_integer() | infinity +---- Maximum number of connections allowed on this listener. @@ -47,6 +89,7 @@ opts() = any() | #{ connection_type => worker | supervisor, handshake_timeout => timeout(), max_connections => max_conns(), + logger => module(), num_acceptors => pos_integer(), shutdown => timeout() | brutal_kill, socket => any(), @@ -64,7 +107,12 @@ option needs to be given) or as part of `socket_opts`. The different options are described further down in this document. -=== ref() = any() +=== ref() + +[source,erlang] +---- +ref() = any() +---- Unique name used to refer to a listener. @@ -89,7 +137,8 @@ Maximum allowed time for the `ranch:handshake/1,2` call to finish. max_connections (1024):: -Maximum number of active connections. Soft limit. Using `infinity` will disable the limit entirely. +Maximum number of active connections. Soft limit. +Use `infinity` to disable the limit entirely. num_acceptors (10):: @@ -101,246 +150,21 @@ Maximum allowed time for children to stop on listener shutdown. socket:: -Listening socket opened externally to be used instead of calling `Transport:listen/1`. +Listening socket opened externally to be used instead of +calling `Transport:listen/1`. This option will be removed +in Ranch 2.0. Use a custom transport module acting as a +wrapper for `ranch_tcp` or `ranch_ssl` instead. socket_opts:: -Socket options given to the `Transport:listen/1`. Please refer to the +Socket options given to `Transport:listen/1`. Please refer to the documentation of the transport module you are using for more details. -== Exports - -=== accept_ack(Ref) -> ok - -This function is deprecated in favor of `ranch:handshake/1,2`. - -=== child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> supervisor:child_spec() - -Ref = ref():: Listener name. -NumAcceptors = non_neg_integer():: Number of acceptor processes. -Transport = module():: Transport module. -TransOpts = any():: Transport options. -Protocol = module():: Protocol module. -ProtoOpts = any():: Protocol options. - -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_addr(Ref) -> {IP, Port} - -Ref = ref():: Listener name. -IP = inet:ip_address():: IP of the interface used by this listener. -Port = inet:port_number():: Port number used by this listener. - -Return the IP address and port for the given listener. - -=== get_max_connections(Ref) -> MaxConns - -Ref = ref():: Listener name. -MaxConns = max_conns():: Current maximum number of connections. - -Return the max number of connections allowed for the given listener. - -=== get_port(Ref) -> Port - -Ref = ref():: Listener name. -Port = inet:port_number():: Port number used by this listener. - -Return the port for the given listener. - -=== get_protocol_options(Ref) -> ProtoOpts - -Ref = ref():: Listener name. -ProtoOpts = any():: Current protocol options. - -Return the protocol options set for the given listener. - -=== get_status(Ref) -> running | suspended - -Ref = ref():: Listener name. - -Return the status of the given listener. - -=== get_transport_options(Ref) -> TransOpts - -Ref = ref():: Listener name. -TransOpts = any():: Current transport options. - -Return the transport options set for the given listener. - -=== handshake(Ref) -> {ok, Socket} - -Ref = ref():: Listener name. -Socket = any():: Initialized socket. - -Acknowledge that the connection is accepted. -Returns a socket that is ready to use. - -One of the `ranch:handshake/{1,2}` functions 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. - -=== handshake(Ref, Opts) -> {ok, Socket} - -Ref = ref():: Listener name. -Opts = any():: Initialization options. -Socket = any():: Initialized socket. - -Acknowledge that the connection is accepted. -Additional options can be provided for socket initialization. -Returns a socket that is ready to use. - -One of the `ranch:handshake/{1,2}` functions 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. - -=== info() -> [{Ref, [{Key, Value}]}] - -Ref = ref():: Listener name. -Key = atom():: Information key. -Value = any():: Information value. - -Return detailed information about all Ranch listeners. - -The following keys are defined: - -pid:: Pid of the listener's top-level supervisor. -status:: Listener status, either running or suspended. -ip:: Interface Ranch listens on. -port:: Port number Ranch listens on. -num_acceptors:: Number of acceptor processes. -max_connections:: Maximum number of connections. -active_connections:: Number of active connections. -all_connections:: Number of connections, including those removed from the count. -transport:: Transport module. -transport_options:: Transport options. -protocol:: Protocol module. -protocol_options:: Protocol options. - -=== info(Ref) -> [{Key, Value}] - -Ref = ref():: Listener name. -Key = atom():: Information key. -Value = any():: Information value. - -Return detailed information about a specific Ranch listener. - -See `info/0` for a description of the defined keys. - -=== procs(Ref, acceptors | connections) -> [pid()] - -Ref = ref():: Listener name. - -Return all acceptor or connection processes for one listener. - -=== remove_connection(Ref) -> ok - -Ref = ref():: Listener name. - -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. - -=== resume_listener(Ref) -> ok - -Ref = ref():: Listener name. - -Resume the given listener if it is suspended. -If the listener is already running, nothing will happen. - -The listener will be started with the transport options -currently set for it. - -=== set_max_connections(Ref, MaxConns) -> ok - -Ref = ref():: Listener name. -MaxConns = max_conns():: New maximum number of connections. - -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 - -Ref = ref():: Listener name. -ProtoOpts = any():: New protocol options. - -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. - -=== set_transport_options(Ref, TransOpts) -> ok | {error, running} - -Ref = ref():: Listener name. -ProtoOpts = any():: New transport options. - -Set the transport options for the given listener. - -The listener must be suspended for this call to succeed. -If the listener is running, `{error, running}` will be returned. - -The change will take effect when the listener is being resumed. - -=== start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> {ok, pid()} | {error, badarg} - -Ref = ref():: Listener name. -NumAcceptors = non_neg_integer():: Number of acceptor processes. -Transport = module():: Transport module. -TransOpts = any():: Transport options. -Protocol = module():: Protocol module. -ProtoOpts = any():: Protocol options. - -Start listening for connections using the given transport -and protocol. Returns the pid for this listener's supervisor. - -There are additional transport options that apply -regardless of transport. They allow configuring how the -connections are supervised, rate limited and more. Please -consult the previous section for more details. - -=== stop_listener(Ref) -> ok | {error, not_found} - -Ref = ref():: Listener name. - -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. - -=== suspend_listener(Ref) -> ok - -Ref = ref():: Listener name. - -Suspend the given listener if it is running. -If the listener is already suspended, nothing will happen. - -The listener will stop listening and accepting connections by -closing the listening port, but will not stop running connection -processes. +== Changelog -=== wait_for_connections(Ref, Operator, NumConnections) -> ok +* *1.6*: The `logger` option was added. +* *1.6*: The `opt()` type was deprecated in favor of the new `opts()` type. -Ref = ref():: Listener name. -Operator = '>' | '>=' | '==' | '=<' | '<':: Comparison operator. -NumConnections = non_neg_integer():: Number of connections to wait for. +== See also -Wait until the number of connections on the given listener matches -the given operator and number of connections. +link:man:ranch(7)[ranch(7)] diff --git a/doc/src/manual/ranch.child_spec.asciidoc b/doc/src/manual/ranch.child_spec.asciidoc new file mode 100644 index 0000000..88a7581 --- /dev/null +++ b/doc/src/manual/ranch.child_spec.asciidoc @@ -0,0 +1,103 @@ += ranch:child_spec(3) + +== Name + +ranch:child_spec - Build child specifications for a new listener + +== Description + +[source,erlang] +---- +child_spec(Ref :: ranch_ref(), + Transport :: module(), + TransOpts :: ranch:opts(), + Protocol :: module(), + ProtoOpts :: any()) + -> supervisor:child_spec() +---- + +Build child specifications for a new listener. + +This function can be used to embed a listener directly +in an application's supervision tree. + +== Arguments + +Ref:: + +The listener name is used to refer to this listener in +future calls, for example when stopping it or when +updating the configuration. ++ +It can be any Erlang term. An atom is generally good enough, +for example `api`, `my_app_clear` or `my_app_tls`. + +Transport:: + +The transport module that will be used by Ranch to accept +connections and that will be passed to the protocol module +along with the socket. ++ +The interface of the transport module is documented in the +link:man:ranch_transport(3)[ranch_transport(3)] manual. + +TransportOpts:: + +Transport options include the Ranch-specific options +and the socket options. The listener's port number must +be defined in the socket options. ++ +Socket options may be given directly if there are no +Ranch-specific options. ++ +The available options for the built-in Ranch transports +are documented in the link:man:ranch_tcp(3)[ranch_tcp(3)] +and link:man:ranch_ssl(3)[ranch_ssl(3)] manuals. + +Protocol:: + +The protocol module that will be used by Ranch after +the connection has been accepted. ++ +The interface of the protocol module is documented in the +link:man:ranch_protocol(3)[ranch_protocol(3)] manual. + +ProtocolOpts:: + +The protocol options given when calling the protocol +module. Please consult the documentation of the protocol +module you are using for more details. + +== Return value + +Child specifications are returned. + +== Changelog + +* *1.4*: The `NumAcceptors` argument was moved to the transport options. + +== Examples + +.Embed a listener +[source,erlang] +---- +-behavior(supervisor). + +init(_) -> + {ok, {#{strategy => one_for_one}, [ + ranch:child_spec(echo, + ranch_tcp, [{port, 5555}], + echo_protocol, [] + ) + ]}}. +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch(3)[ranch(3)], +link:man:ranch_tcp(3)[ranch_tcp(3)], +link:man:ranch_ssl(3)[ranch_ssl(3)], +link:man:ranch_transport(3)[ranch_transport(3)], +link:man:ranch_protocol(3)[ranch_protocol(3)] diff --git a/doc/src/manual/ranch.get_addr.asciidoc b/doc/src/manual/ranch.get_addr.asciidoc new file mode 100644 index 0000000..3938347 --- /dev/null +++ b/doc/src/manual/ranch.get_addr.asciidoc @@ -0,0 +1,44 @@ += ranch:get_addr(3) + +== Name + +ranch:get_addr - Get the listening port and IP + +== Description + +[source,erlang] +---- +get_addr(Ref :: ranch:ref()) + -> {IP :: inet:ip_address(), + Port :: inet:port_number()} +---- + +Get the listening port and IP. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The address of the listener is returned as a tuple. + +The IP address is the IP of the network interface the +socket is bound to. + +== Examples + +.Get the listening port and IP +[source,erlang] +---- +{IP, Port} = ranch:get_addr(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:get_port(3)[ranch:get_port(3)], +link:man:ranch:info(3)[ranch:info(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.get_max_connections.asciidoc b/doc/src/manual/ranch.get_max_connections.asciidoc new file mode 100644 index 0000000..3267c2d --- /dev/null +++ b/doc/src/manual/ranch.get_max_connections.asciidoc @@ -0,0 +1,40 @@ += ranch:get_max_connections(3) + +== Name + +ranch:get_max_connections - Get the max number of connections + +== Description + +[source,erlang] +---- +get_max_connections(Ref :: ranch:ref()) + -> MaxConns :: ranch:max_conns() +---- + +Get the max number of connections. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The maximum number of connections is returned. + +== Examples + +.Get the max number of connections +[source,erlang] +---- +MaxConns = ranch:get_max_connections(example). +---- + +== See also + +link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)], +link:man:ranch:get_transport_options(3)[ranch:get_transport_options(3)], +link:man:ranch:set_max_connections(3)[ranch:set_max_connections(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.get_port.asciidoc b/doc/src/manual/ranch.get_port.asciidoc new file mode 100644 index 0000000..0de4a3a --- /dev/null +++ b/doc/src/manual/ranch.get_port.asciidoc @@ -0,0 +1,44 @@ += ranch:get_port(3) + +== Name + +ranch:get_port - Get the listening port + +== Description + +[source,erlang] +---- +get_port(Ref :: ranch:ref()) + -> Port :: inet:port_number() +---- + +Get the listening port. + +This function is particularly useful to retrieve the +listening port number when it was not provided in the +options and was chosen randomly instead. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The listening port is returned. + +== Examples + +.Get the listening port +[source,erlang] +---- +Port = ranch:get_port(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:get_addr(3)[ranch:get_addr(3)], +link:man:ranch:info(3)[ranch:info(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.get_protocol_options.asciidoc b/doc/src/manual/ranch.get_protocol_options.asciidoc new file mode 100644 index 0000000..b5b2a9e --- /dev/null +++ b/doc/src/manual/ranch.get_protocol_options.asciidoc @@ -0,0 +1,40 @@ += ranch:get_protocol_options(3) + +== Name + +ranch:get_protocol_options - Get the current protocol options + +== Description + +[source,erlang] +---- +get_protocol_options(Ref :: ranch:ref()) + -> ProtoOpts :: any() +---- + +Get the current protocol options. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The current protocol options are returned. + +== Examples + +.Get the current protocol options +[source,erlang] +---- +ProtoOpts = ranch:get_protocol_options(example). +---- + +== See also + +link:man:ranch:get_max_connections(3)[ranch:get_max_connections(3)], +link:man:ranch:get_transport_options(3)[ranch:get_transport_options(3)], +link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.get_status.asciidoc b/doc/src/manual/ranch.get_status.asciidoc new file mode 100644 index 0000000..eb45614 --- /dev/null +++ b/doc/src/manual/ranch.get_status.asciidoc @@ -0,0 +1,46 @@ += ranch:get_status(3) + +== Name + +ranch:get_status - Get a listener's running state + +== Description + +[source,erlang] +---- +get_status(Ref :: ranch_ref()) -> running | suspended +---- + +Get a listener's running state. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +An atom is returned indicating the running status of the listener. + +== Changelog + +* *1.6*: Function introduced. + +== Examples + +.Get a listener's running state +[source,erlang] +---- +ranch:get_status(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], +link:man:ranch:resume_listener(3)[ranch:resume_listener(3)], +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], +link:man:ranch:wait_for_connections(3)[ranch:wait_for_connections(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.get_transport_options.asciidoc b/doc/src/manual/ranch.get_transport_options.asciidoc new file mode 100644 index 0000000..438df90 --- /dev/null +++ b/doc/src/manual/ranch.get_transport_options.asciidoc @@ -0,0 +1,40 @@ += ranch:get_transport_options(3) + +== Name + +ranch:get_transport_options - Get the current transport options + +== Description + +[source,erlang] +---- +get_transport_options(Ref :: ranch:ref()) + -> TransOpts :: any() +---- + +Get the current transport options. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The current transport options are returned. + +== Examples + +.Get the current transport options +[source,erlang] +---- +TransOpts = ranch:get_transport_options(example). +---- + +== See also + +link:man:ranch:get_max_connections(3)[ranch:get_max_connections(3)], +link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)], +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.handshake.asciidoc b/doc/src/manual/ranch.handshake.asciidoc new file mode 100644 index 0000000..e2c7da9 --- /dev/null +++ b/doc/src/manual/ranch.handshake.asciidoc @@ -0,0 +1,74 @@ += ranch:handshake(3) + +== Name + +ranch:handshake - Perform the transport handshake + +== Description + +[source,erlang] +---- +handshake(Ref) -> handshake(Ref, []) +handshake(Ref, Opts) -> {ok, Socket} + +Ref :: ranch:ref() +Opts :: any() +Socket :: any() +---- + +Perform the transport handshake. + +This function must be called by the protocol process in order +to retrieve the socket for the connection. Ranch performs the +handshake necessary to give control of the socket to this +process and also does the transport handshake, for example +setting up the TLS connection. + +Currently the socket can be obtained from a +`Protocol:start_link/4` argument and as a return value +from `ranch:handshake/1,2`. In Ranch 2.0 the socket will +only be available from `ranch:handshake/1,2`. + +== Arguments + +Ref:: + +The listener name. + +Opts:: + +Transport handshake options. ++ +Allowed options depend on the transport module. + +== Return value + +An `ok` tuple is returned containing the socket for the connection. + +This function will trigger an exception when an error occurs. + +== Changelog + +* *1.6*: Function introduced. Replaces `ranch:accept_ack/1`. + +== Examples + +.Initialize the connection process +[source,erlang] +---- +start_link(Ref, _, Transport, Opts) -> + Pid = proc_lib:spawn_link(?MODULE, init, + [Ref, Transport, Opts]), + {ok, Pid}. + +init(Ref, Transport, Opts) -> + {ok, Socket} = ranch:handshake(Ref), + loop(#state{ref=Ref, socket=Socket, + transport=Transport, opts=Opts}). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:remove_connection(3)[ranch:remove_connection(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.info.asciidoc b/doc/src/manual/ranch.info.asciidoc new file mode 100644 index 0000000..32cbefb --- /dev/null +++ b/doc/src/manual/ranch.info.asciidoc @@ -0,0 +1,65 @@ += ranch:info(3) + +== Name + +ranch:info - Overview of Ranch listeners + +== Description + +[source,erlang] +---- +info() -> [{Ref, Info}] +info(Ref) -> Info + +Info :: [{Key :: atom(), Value :: any()}] +---- + +Overview of Ranch listeners. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +Returns detailed information about one or all +Ranch listeners. The following keys are returned: + +pid:: Pid of the listener's top-level supervisor. +status:: Listener status, either running or suspended. +ip:: Interface Ranch listens on. +port:: Port number Ranch listens on. +num_acceptors:: Number of acceptor processes. +max_connections:: Maximum number of connections. +active_connections:: Number of active connections. +all_connections:: Number of connections, including those removed from the count. +transport:: Transport module. +transport_options:: Transport options. +protocol:: Protocol module. +protocol_options:: Protocol options. + +// @todo I mistakenly removed the num_acceptors key, +// it should be added back. + +== Examples + +.Get information about all listeners +[source,erlang] +---- +AllInfo = ranch:info(). +---- + +.Get information about a specific listener +[source,erlang] +---- +Info = ranch:info(example). +---- + +== See also + +link:man:ranch:get_addr(3)[ranch:get_addr(3)], +link:man:ranch:get_port(3)[ranch:get_port(3)], +link:man:ranch:procs(3)[ranch:procs(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.procs.asciidoc b/doc/src/manual/ranch.procs.asciidoc new file mode 100644 index 0000000..0f29533 --- /dev/null +++ b/doc/src/manual/ranch.procs.asciidoc @@ -0,0 +1,51 @@ += ranch:procs(3) + +== Name + +ranch:procs - Retrieve pids from a listener + +== Description + +[source,erlang] +---- +procs(Ref :: ranch:ref(), + Type :: acceptors | connections) + -> Pids :: [pid()] +---- + +Retrieve pids from a listener. + +== Arguments + +Ref:: + +The listener name. + +Type:: + +The type of process that will be returned. + +== Return value + +A list of pids is returned. + +== Examples + +.Get the pids of the acceptor processes +[source,erlang] +---- +Pids = ranch:procs(acceptors). +---- + +.Get the pids of the connection processes +[source,erlang] +---- +Pids = ranch:procs(connections). +---- + +== See also + +link:man:ranch:get_addr(3)[ranch:get_addr(3)], +link:man:ranch:get_port(3)[ranch:get_port(3)], +link:man:ranch:info(3)[ranch:info(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.remove_connection.asciidoc b/doc/src/manual/ranch.remove_connection.asciidoc new file mode 100644 index 0000000..59f79f1 --- /dev/null +++ b/doc/src/manual/ranch.remove_connection.asciidoc @@ -0,0 +1,46 @@ += ranch:remove_connection(3) + +== Name + +ranch:remove_connection - Remove connection from the count + +== Description + +[source,erlang] +---- +remove_connection(Ref :: ranch:ref()) -> ok +---- + +Remove connection from the count. + +This connection will no longer be included in the count when +limiting the number of connections. This can be useful in a +mixed environment where some connections are active and others +are passive. Passive connections spend most of their time idling +and are not consuming much resources. + +This function may only be called from a connection process. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Examples + +.Remove the connection process from the count +[source,erlang] +---- +ranch:remove_connection(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:handshake(3)[ranch:handshake(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.resume_listener.asciidoc b/doc/src/manual/ranch.resume_listener.asciidoc new file mode 100644 index 0000000..f3a9f84 --- /dev/null +++ b/doc/src/manual/ranch.resume_listener.asciidoc @@ -0,0 +1,57 @@ += ranch:resume_listener(3) + +== Name + +ranch:resume_listener - Resume a suspended listener + +== Description + +[source,erlang] +---- +resume_listener(Ref :: ranch_ref()) + -> ok | {error, any()} +---- + +Resume a suspended listener. + +Ranch will start listening for and accepting connections +again. The function +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)] +can be used to change the transport options before resuming +the listener. + +Nothing is done when the listener is already running. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The atom `ok` is returned on success. + +An error tuple is returned when the listener could not be restarted. + +== Changelog + +* *1.6*: Function introduced. + +== Examples + +.Resume a listener +[source,erlang] +---- +ok = ranch:resume_listener(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], +link:man:ranch:get_status(3)[ranch:get_status(3)], +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], +link:man:ranch:wait_for_connections(3)[ranch:wait_for_connections(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.set_max_connections.asciidoc b/doc/src/manual/ranch.set_max_connections.asciidoc new file mode 100644 index 0000000..2559afe --- /dev/null +++ b/doc/src/manual/ranch.set_max_connections.asciidoc @@ -0,0 +1,50 @@ += ranch:set_max_connections(3) + +== Name + +ranch:set_max_connections - Set the max number of connections + +== Description + +[source,erlang] +---- +set_max_connections(Ref :: ranch:ref(), + MaxConns :: ranch:max_conns()) + -> ok +---- + +Set the max number of connections. + +The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will wait for the extra +connections to terminate and will not accept new connections +until the number of connections goes below the limit. + +== Arguments + +Ref:: + +The listener name. + +MaxConns:: + +The new maximum number of connections. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Examples + +.Set the max number of connections +[source,erlang] +---- +ranch:set_max_connections(example, 10000). +---- + +== See also + +link:man:ranch:get_max_connections(3)[ranch:get_max_connections(3)], +link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)], +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.set_protocol_options.asciidoc b/doc/src/manual/ranch.set_protocol_options.asciidoc new file mode 100644 index 0000000..1851fab --- /dev/null +++ b/doc/src/manual/ranch.set_protocol_options.asciidoc @@ -0,0 +1,48 @@ += ranch:set_protocol_options(3) + +== Name + +ranch:set_protocol_options - Set the protocol options + +== Description + +[source,erlang] +---- +set_protocol_options(Ref :: ranch:ref(), + ProtoOpts :: any()) + -> ok +---- + +Set the protocol options. + +The change will be applied immediately for all new connections. +Old connections will not receive the new options. + +== Arguments + +Ref:: + +The listener name. + +ProtoOpts:: + +The new protocol options. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Examples + +.Set the protocol options +[source,erlang] +---- +ranch:set_protocol_options(example, ProtoOpts). +---- + +== See also + +link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)], +link:man:ranch:set_max_connections(3)[ranch:set_max_connections(3)], +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.set_transport_options.asciidoc b/doc/src/manual/ranch.set_transport_options.asciidoc new file mode 100644 index 0000000..51bc3f7 --- /dev/null +++ b/doc/src/manual/ranch.set_transport_options.asciidoc @@ -0,0 +1,56 @@ += ranch:set_transport_options(3) + +== Name + +ranch:set_transport_options - Set the transport options + +== Description + +[source,erlang] +---- +set_transport_options(Ref :: ranch:ref(), + TransOpts :: any()) + -> ok | {error, running} +---- + +Set the transport options. + +The listener must be suspended for this call to succeed. +If the listener is running, `{error, running}` will be returned. + +The change will take effect when the listener resumes. + +== Arguments + +Ref:: + +The listener name. + +TransOpts:: + +The new transport options. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Examples + +.Set the transport options +[source,erlang] +---- +Ref = example, + +ok = ranch:suspend_listener(Ref), +ok = ranch:set_transport_options(Ref, TransOpts), +ok = ranch:resume_listener(Ref). +---- + +== See also + +link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], +link:man:ranch:resume_listener(3)[ranch:resume_listener(3)], +link:man:ranch:get_transport_options(3)[ranch:get_transport_options(3)], +link:man:ranch:set_max_connections(3)[ranch:set_max_connections(3)], +link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.start_listener.asciidoc b/doc/src/manual/ranch.start_listener.asciidoc new file mode 100644 index 0000000..d73800c --- /dev/null +++ b/doc/src/manual/ranch.start_listener.asciidoc @@ -0,0 +1,131 @@ += ranch:start_listener(3) + +== Name + +ranch:start_listener - Start a listener + +== Description + +[source,erlang] +---- +start_listener(Ref :: ranch_ref(), + Transport :: module(), + TransOpts :: ranch:opts(), + Protocol :: module(), + ProtoOpts :: any()) + -> {ok, ListenerPid :: pid()} + | {error, any()} +---- + +Start a listener. + +A listener is a set of processes that accepts and manages +connections using the given transport and protocol modules. + +== Arguments + +Ref:: + +The listener name is used to refer to this listener in +future calls, for example when stopping it or when +updating the configuration. ++ +It can be any Erlang term. An atom is generally good enough, +for example `api`, `my_app_clear` or `my_app_tls`. + +Transport:: + +The transport module that will be used by Ranch to accept +connections and that will be passed to the protocol module +along with the socket. ++ +The interface of the transport module is documented in the +link:man:ranch_transport(3)[ranch_transport(3)] manual. + +TransportOpts:: + +Transport options include the Ranch-specific options +and the socket options. The listener's port number must +be defined in the socket options. ++ +Socket options may be given directly if there are no +Ranch-specific options. ++ +The available options for the built-in Ranch transports +are documented in the link:man:ranch_tcp(3)[ranch_tcp(3)] +and link:man:ranch_ssl(3)[ranch_ssl(3)] manuals. + +Protocol:: + +The protocol module that will be used by Ranch after +the connection has been accepted. ++ +The interface of the protocol module is documented in the +link:man:ranch_protocol(3)[ranch_protocol(3)] manual. + +ProtocolOpts:: + +The protocol options given when calling the protocol +module. Please consult the documentation of the protocol +module you are using for more details. + +== Return value + +An ok tuple is returned on success. It contains the pid of +the top-level supervisor for the listener. + +An error tuple is returned on error. The error reason may +be any Erlang term. + +A common error is `eaddrinuse`. It indicates that the port +configured for Ranch is already in use. + +== Changelog + +* *1.4*: The `NumAcceptors` argument was moved to the transport options. + +== Examples + +.Start a listener +[source,erlang] +---- +{ok, _} = ranch:start_listener(example, + ranch_tcp, [{port, 8080}], + cowboy_http2, #{} +). +---- + +.Start a listener with Ranch-specific options +[source,erlang] +---- +{ok, _} = ranch:start_listener(example, + ranch_tcp, #{ + num_acceptors => 75, + socket_opts => [{port, 8080}] + }, + cowboy_http2, #{} +). +---- + +.Start a listener on a random port +[source,erlang] +---- +Ref = example, + +{ok, _} = ranch:start_listener(Ref, + ranch_tcp, #{}, + cowboy_http2, #{} +), + +Port = ranch:get_port(Ref). +---- + +== See also + +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch:child_spec(3)[ranch:child_spec(3)], +link:man:ranch(3)[ranch(3)], +link:man:ranch_tcp(3)[ranch_tcp(3)], +link:man:ranch_ssl(3)[ranch_ssl(3)], +link:man:ranch_transport(3)[ranch_transport(3)], +link:man:ranch_protocol(3)[ranch_protocol(3)] diff --git a/doc/src/manual/ranch.stop_listener.asciidoc b/doc/src/manual/ranch.stop_listener.asciidoc new file mode 100644 index 0000000..6de24f5 --- /dev/null +++ b/doc/src/manual/ranch.stop_listener.asciidoc @@ -0,0 +1,58 @@ += ranch:stop_listener(3) + +== Name + +ranch:stop_listener - Stop a listener + +== Description + +[source,erlang] +---- +stop_listener(Ref :: ranch_ref()) + -> ok | {error, not_found} +---- + +Stop a 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. + +In order for the connection processes to exit gracefully, +they need to trap exit signals and stop before the configured +shutdown timeout. If greater control over the shutdown is +required the functions link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)] +and link:man:ranch:wait_for_connections(3)[ranch:wait_for_connections(3)] +can be used. + +This function does not return until the listener is +completely stopped. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The atom `ok` is returned on success. + +An error tuple is returned when the listener is not found. + +== Examples + +.Stop a listener +[source,erlang] +---- +ok = ranch:stop_listener(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:child_spec(3)[ranch:child_spec(3)], +link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.suspend_listener.asciidoc b/doc/src/manual/ranch.suspend_listener.asciidoc new file mode 100644 index 0000000..322b993 --- /dev/null +++ b/doc/src/manual/ranch.suspend_listener.asciidoc @@ -0,0 +1,62 @@ += ranch:suspend_listener(3) + +== Name + +ranch:suspend_listener - Suspend a running listener + +== Description + +[source,erlang] +---- +suspend_listener(Ref :: ranch_ref()) + -> ok | {error, any()} +---- + +Suspend a running listener. + +Ranch will stop listening for and accepting connections and +the listening socket will be closed. Existing connections +will continue undisturbed. The function +link:man:ranch:wait_for_connections(3)[ranch:wait_for_connections(3)] +can be used to wait for connections to be closed if necessary. + +Some transport options can only be changed when the listener is +suspended. Please consult the +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)] +manual for more information. + +Nothing is done when the listener is already suspended. + +== Arguments + +Ref:: + +The listener name. + +== Return value + +The atom `ok` is returned on success. + +An error tuple is returned when the listener could not be suspended. + +== Changelog + +* *1.6*: Function introduced. + +== Examples + +.Suspend a listener +[source,erlang] +---- +ok = ranch:suspend_listener(example). +---- + +== See also + +link:man:ranch:start_listener(3)[ranch:start_listener(3)], +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch:resume_listener(3)[ranch:resume_listener(3)], +link:man:ranch:get_status(3)[ranch:get_status(3)], +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], +link:man:ranch:wait_for_connections(3)[ranch:wait_for_connections(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch.wait_for_connections.asciidoc b/doc/src/manual/ranch.wait_for_connections.asciidoc new file mode 100644 index 0000000..3fdc2a1 --- /dev/null +++ b/doc/src/manual/ranch.wait_for_connections.asciidoc @@ -0,0 +1,76 @@ += ranch:wait_for_connections(3) + +== Name + +ranch:wait_for_connections - Wait for a specific number of connections + +== Description + +[source,erlang] +---- +wait_for_connections(Ref :: ranch:ref(), + Operator, + NumConns :: non_neg_integer()) + -> ok + +Operator :: '>' | '>=' | '==' | '=<' | '<' +---- + +Wait for a specific number of connections. + +This function waits until the number of connections on the +given listener becomes higher than, equal to or lower than +the given number. It never returns otherwise. + +This function can be used to gracefully shutdown a listener +by first suspending the listener and then waiting for +connections to terminate before finally stopping the listener. + +// @todo The suspend/wait/stop pattern should be tested. + +== Arguments + +Ref:: + +The listener name. + +Operator:: + +The operator to use for the comparison. + +NumConns:: + +The number of connections to reach. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Changelog + +* *1.6*: Function introduced. + +== Examples + +.Wait for at least 100 connections +[source,erlang] +---- +ranch:wait_for_connections(example, '>=', 100). +---- + +.Gracefully shutdown a listener +[source,erlang] +---- +Ref = example, + +ok = ranch:suspend_listener(Ref), +ranch:wait_for_connections(Ref, '==', 0), +ok = ranch:stop_listener(Ref). +---- + +== See also + +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], +link:man:ranch:resume_listener(3)[ranch:resume_listener(3)], +link:man:ranch(3)[ranch(3)] diff --git a/doc/src/manual/ranch_app.asciidoc b/doc/src/manual/ranch_app.asciidoc index f5b6e00..5eca83a 100644 --- a/doc/src/manual/ranch_app.asciidoc +++ b/doc/src/manual/ranch_app.asciidoc @@ -2,14 +2,42 @@ == Name -ranch - Socket acceptor pool for TCP protocols. +ranch - Socket acceptor pool for TCP protocols + +== Description + +Ranch is a socket acceptor pool for TCP protocols. + +Ranch manages listeners which are a set of processes that +accept and manage connections. The connection's transport +and protocol modules are configured per listener. Listeners +can be inspected and reconfigured without interruptions in +service. + +== Modules + +Functions: + +* link:man:ranch(3)[ranch(3)] - Socket acceptor pool +* link:man:ranch_ssl(3)[ranch_ssl(3)] - SSL transport +* link:man:ranch_tcp(3)[ranch_tcp(3)] - TLS transport + +Behaviors: + +* link:man:ranch_protocol(3)[ranch_protocol(3)] - Protocol modules +* link:man:ranch_transport(3)[ranch_transport(3)] - Transport modules == Dependencies -The `ranch` application depends on the `ssl` application to -start. It is used for handling secure connections, when the -transport is `ranch_ssl`. It can be disabled if SSL is not -used. +* ssl - Secure communication over sockets + +All these applications must be started before the `ranch` +application. To start Ranch and all dependencies at once: + +[source,erlang] +---- +{ok, _} = application:ensure_all_started(ranch). +---- == Environment @@ -17,8 +45,13 @@ The `ranch` application defines one application environment configuration parameter. profile (false):: - When enabled, Ranch will start `eprof` profiling automatically. +When enabled, Ranch will start `eprof` profiling automatically. ++ You can use the `ranch_app:profile_output/0` function to stop profiling and output the results to the files 'procs.profile' and 'total.profile'. Do not use in production. + +== See also + +ssl(7) -- cgit v1.2.3