From 2730f7188738cc7b1100e50bcc8567d33ecb3934 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Wed, 31 May 2017 14:11:38 +0200
Subject: 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/listeners.asciidoc | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

(limited to 'doc/src/guide/listeners.asciidoc')

diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 1055b80..97afa22 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/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.
-- 
cgit v1.2.3