Deprecated ranch:start_listener/6 and child_spec/6

The NumAcceptors argument has been moved to transport option
num_acceptor, which defaults to 10. The functions now take
one less argument. The old functions are still here, though
deprecated.

doc/src/guide/embedded.asciidoc

@@ -17,7 +17,7 @@ regardless of the number of listeners you will use. Then you need to
 add the child specs for each listener.
 
 Ranch has a convenience function for getting the listeners child specs
-called `ranch:child_spec/6`, that works like `ranch:start_listener/6`,
+called `ranch:child_spec/5`, that works like `ranch:start_listener/5`,
 except that it doesn't start anything, it only returns child specs.
 
 As for `ranch_sup`, the child spec is simple enough to not require a

doc/src/guide/internals.asciidoc

@@ -47,7 +47,7 @@ that new process.
 
 === Number of acceptors
 
-The second argument to `ranch:start_listener/6` is the number of
+The second argument to `ranch:start_listener/5` is the number of
 processes that will be accepting connections. Care should be taken
 when choosing this number.
 

doc/src/guide/listeners.asciidoc

@@ -26,7 +26,7 @@ When starting a listener, a number of different settings are required:
 Ranch includes both TCP and SSL transport handlers, respectively
 `ranch_tcp` and `ranch_ssl`.
 
-A listener can be started by calling the `ranch:start_listener/6`
+A listener can be started by calling the `ranch:start_listener/5`
 function. Before doing so however, you must ensure that the `ranch`
 application is started.
 
@@ -42,7 +42,7 @@ to the `echo_protocol` handler.
 .Starting a listener for TCP connections on port 5555
 
 [source,erlang]
-{ok, _} = ranch:start_listener(tcp_echo, 100,
+{ok, _} = ranch:start_listener(tcp_echo,
 	ranch_tcp, [{port, 5555}],
 	echo_protocol, []
 ).
@@ -108,12 +108,12 @@ the port number 0, or if you omit the port number entirely, Ranch will
 start listening on a random port.
 
 You can retrieve this port number by calling `ranch:get_port/1`. The
-argument is the name of the listener you gave in `ranch:start_listener/6`.
+argument is the name of the listener you gave in `ranch:start_listener/5`.
 
 .Starting a listener for TCP connections on a random port
 
 [source,erlang]
-{ok, _} = ranch:start_listener(tcp_echo, 100,
+{ok, _} = ranch:start_listener(tcp_echo,
 	ranch_tcp, [{port, 0}],
 	echo_protocol, []
 ).
@@ -159,7 +159,7 @@ connections are handled optimally.
 .Customizing the maximum number of concurrent connections
 
 [source,erlang]
-{ok, _} = ranch:start_listener(tcp_echo, 100,
+{ok, _} = ranch:start_listener(tcp_echo,
 	ranch_tcp, [{port, 5555}, {max_connections, 100}],
 	echo_protocol, []
 ).
@@ -169,7 +169,7 @@ You can disable this limit by setting its value to the atom `infinity`.
 .Disabling the limit for the number of connections
 
 [source,erlang]
-{ok, _} = ranch:start_listener(tcp_echo, 100,
+{ok, _} = ranch:start_listener(tcp_echo,
 	ranch_tcp, [{port, 5555}, {max_connections, infinity}],
 	echo_protocol, []
 ).
@@ -213,6 +213,24 @@ ranch:set_max_connections(tcp_echo, MaxConns).
 
 The change will occur immediately.
 
+=== Customizing the number of acceptor processes
+
+By default Ranch will use 10 acceptor processes. Their role is
+to accept connections and spawn a connection process for every
+new connection.
+
+This number can be tweaked to improve performance. A good
+number is typically between 10 or 100 acceptors. You must
+measure to find the best value for your application.
+
+.Specifying a custom number of acceptor processes
+
+[source,erlang]
+{ok, _} = ranch:start_listener(tcp_echo,
+	ranch_tcp, [{port, 5555}, {num_acceptors, 42}],
+	echo_protocol, []
+).
+
 === When running out of file descriptors
 
 Operating systems have limits on the number of sockets
@@ -278,7 +296,7 @@ calling `ranch:get_protocol_options/1`.
 [source,erlang]
 Opts = ranch:get_protocol_options(tcp_echo).
 
-=== Obtain information about listeners
+=== Obtaining information about listeners
 
 Ranch provides two functions for retrieving information about the
 listeners, for reporting and diagnostic purposes.

doc/src/guide/protocols.asciidoc

@@ -10,7 +10,7 @@ which defines a single callback, `start_link/4`. This callback is
 responsible for spawning a new process for handling the connection.
 It receives four arguments: the name of the listener, the socket, the
 transport handler being used and the protocol options defined in
-the call to `ranch:start_listener/6`. This callback must
+the call to `ranch:start_listener/5`. This callback must
 return `{ok, Pid}`, with `Pid` the pid of the new process.
 
 The newly started process can then freely initialize itself. However,

doc/src/guide/ssl_auth.asciidoc

@@ -49,7 +49,7 @@ the listener to enable this behavior.
 .Configure a listener for SSL authentication
 
 [source,erlang]
-{ok, _} = ranch:start_listener(my_ssl, 100,
+{ok, _} = ranch:start_listener(my_ssl,
 	ranch_ssl, [
 		{port, SSLPort},
 		{certfile, PathToCertfile},

doc/src/manual/ranch.asciidoc

@@ -28,6 +28,7 @@ code.
 opt() = {ack_timeout, timeout()}
 	| {connection_type, worker | supervisor}
 	| {max_connections, max_conns()}
+	| {num_acceptors, pos_integer()}
 	| {shutdown, timeout() | brutal_kill}
 	| {socket, any()}
 ----
@@ -51,6 +52,8 @@ connection_type (worker)::
 	Type of process that will handle the connection.
 max_connections (1024)::
 	Maximum number of active connections. Soft limit. Using `infinity` will disable the limit entirely.
+num_acceptors (10)::
+	Number of processes that accept connections.
 shutdown (5000)::
 	Maximum allowed time for children to stop on listener shutdown.
 socket::

examples/tcp_echo/src/tcp_echo_app.erl

@@ -11,7 +11,7 @@
 %% API.
 
 start(_Type, _Args) ->
-	{ok, _} = ranch:start_listener(tcp_echo, 1,
+	{ok, _} = ranch:start_listener(tcp_echo,
 		ranch_tcp, [{port, 5555}], echo_protocol, []),
 	tcp_echo_sup:start_link().
 

examples/tcp_reverse/src/tcp_reverse_app.erl

@@ -11,7 +11,7 @@
 %% API.
 
 start(_Type, _Args) ->
-    {ok, _} = ranch:start_listener(tcp_reverse, 10,
+    {ok, _} = ranch:start_listener(tcp_reverse,
 		ranch_tcp, [{port, 5555}], reverse_protocol, []),
     tcp_reverse_sup:start_link().
 

src/ranch.erl

@@ -14,8 +14,10 @@
 
 -module(ranch).
 
+-export([start_listener/5]).
 -export([start_listener/6]).
 -export([stop_listener/1]).
+-export([child_spec/5]).
 -export([child_spec/6]).
 -export([accept_ack/1]).
 -export([remove_connection/1]).
@@ -31,19 +33,28 @@
 -export([set_option_default/3]).
 -export([require/1]).
 
+-deprecated([start_listener/6, child_spec/6]).
+
 -type max_conns() :: non_neg_integer() | infinity.
 -export_type([max_conns/0]).
 
 -type opt() :: {ack_timeout, timeout()}
 	| {connection_type, worker | supervisor}
 	| {max_connections, max_conns()}
+	| {num_acceptors, pos_integer()}
 	| {shutdown, timeout() | brutal_kill}
 	| {socket, any()}.
 -export_type([opt/0]).
 
 -type ref() :: any().
 -export_type([ref/0]).
 
+-spec start_listener(ref(), module(), any(), module(), any())
+	-> supervisor:startchild_ret().
+start_listener(Ref, Transport, TransOpts, Protocol, ProtoOpts) ->
+	NumAcceptors = proplists:get_value(num_acceptors, TransOpts, 10),
+	start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts).
+
 -spec start_listener(ref(), non_neg_integer(), module(), any(), module(), any())
 	-> supervisor:startchild_ret().
 start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts)
@@ -99,6 +110,12 @@ stop_listener(Ref) ->
 			{error, Reason}
 	end.
 
+-spec child_spec(ref(), module(), any(), module(), any())
+	-> supervisor:child_spec().
+child_spec(Ref, Transport, TransOpts, Protocol, ProtoOpts) ->
+	NumAcceptors = proplists:get_value(num_acceptors, TransOpts, 10),
+	child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts).
+
 -spec child_spec(ref(), non_neg_integer(), module(), any(), module(), any())
 	-> supervisor:child_spec().
 child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts)

src/ranch_acceptors_sup.erl

@@ -30,8 +30,9 @@ init([Ref, NumAcceptors, Transport, TransOpts]) ->
 			TransOpts2 = proplists:delete(ack_timeout,
 				proplists:delete(connection_type,
 				proplists:delete(max_connections,
+				proplists:delete(num_acceptors,
 				proplists:delete(shutdown,
-				proplists:delete(socket, TransOpts))))),
+				proplists:delete(socket, TransOpts)))))),
 			case Transport:listen(TransOpts2) of
 				{ok, Socket} -> Socket;
 				{error, Reason} -> listen_error(Ref, Transport, TransOpts2, Reason)