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

@@ -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.

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)

src/ranch.erl

@@ -181,7 +181,7 @@ stop_listener(Ref) ->
 			{error, Reason}
 	end.
 
--spec suspend_listener(ref()) -> ok | {error, term()}.
+-spec suspend_listener(ref()) -> ok | {error, any()}.
 suspend_listener(Ref) ->
 	case get_status(Ref) of
 		running ->
@@ -192,7 +192,7 @@ suspend_listener(Ref) ->
 			ok
 	end.
 
--spec resume_listener(ref()) -> ok | {error, term()}.
+-spec resume_listener(ref()) -> ok | {error, any()}.
 resume_listener(Ref) ->
 	case get_status(Ref) of
 		running ->
@@ -263,7 +263,7 @@ remove_connection(Ref) ->
 	ConnsSup ! {remove_connection, Ref, self()},
 	ok.
 
--spec get_status(ref()) -> running | suspended | restarting.
+-spec get_status(ref()) -> running | suspended.
 get_status(Ref) ->
 	ListenerSup = ranch_server:get_listener_sup(Ref),
 	Children = supervisor:which_children(ListenerSup),

src/ranch_transport.erl

@@ -116,7 +116,7 @@ chunk_size(Opts) ->
 
 -spec sendfile_loop(module(), socket(), file:fd(), non_neg_integer(),
 		non_neg_integer(), pos_integer())
-	-> {ok, non_neg_integer()} | {error, term()}.
+	-> {ok, non_neg_integer()} | {error, any()}.
 sendfile_loop(_Transport, _Socket, _RawFile, Sent, Sent, _ChunkSize)
 		when Sent =/= 0 ->
 	%% All requested data has been read and sent, return number of bytes sent.