Add a manual

This is the manual for what is going to be in 1.0. It includes
two things that are not in the code yet: the shutdown option
and the accept_ack transport callback.

1 files changed, 171 insertions, 0 deletions

diff --git a/manual/ranch.md b/manual/ranch.md
new file mode 100644
index 0000000..cf4ebe5
--- /dev/null
+++ b/manual/ranch.md
@@ -0,0 +1,171 @@
+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.
+
+### 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.