Add the num_conns_sups option

This new option allows configuring the number of connection
supervisors. The old behavior can be obtained by setting this
value to 1. A value larger than num_acceptors will result in
some connection supervisors not being used as the acceptors
currently only use one connection supervisor.

5 files changed, 54 insertions, 17 deletions

diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 4885c6d..e7ecfec 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -182,9 +182,9 @@ socket and that it is operational.
 === Limiting the number of concurrent connections
 
 The `max_connections` transport option allows you to limit the number
-of concurrent connections. It defaults to 1024. Its purpose is to
-prevent your system from being overloaded and ensuring all the
-connections are handled optimally.
+of concurrent connections per connection supervisor (see below).
+It defaults to 1024. Its purpose is to prevent your system from being
+overloaded and ensuring all the connections are handled optimally.
 
 .Customizing the maximum number of concurrent connections
 
@@ -261,6 +261,26 @@ measure to find the best value for your application.
 	echo_protocol, []
 ).
 
+=== Customizing the number of connection supervisors
+
+By default Ranch will use one connection supervisor for each
+acceptor process (but not vice versa). Their task is to
+supervise the connection processes started by an acceptor.
+The number of connection supervisors can be tweaked.
+
+Note that the association between the individual acceptors and
+connection supervisors is fixed, meaning that acceptors will
+always use the same connection supervisor to start connection
+processes.
+
+.Specifying a custom number of connection supervisors
+
+[source,erlang]
+{ok, _} = ranch:start_listener(tcp_echo,
+	ranch_tcp, #{socket_opts => [{port, 5555}], num_conns_sups => 42}],
+	echo_protocol, []
+).
+
 === When running out of file descriptors
 
 Operating systems have limits on the number of sockets
diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index 01de75f..ca8a789 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -32,10 +32,10 @@ Connections:
 
 Options:
 
-* link:man:ranch:get_max_connections(3)[ranch:get_max_connections(3)] - Get the max number of connections
+* link:man:ranch:get_max_connections(3)[ranch:get_max_connections(3)] - Get the max number of connections per connection supervisor
 * 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_max_connections(3)[ranch:set_max_connections(3)] - Set the max number of connections per connection supervisor
 * 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
 
@@ -56,7 +56,7 @@ Introspection:
 max_conns() = non_neg_integer() | infinity
 ----
 
-Maximum number of connections allowed on this listener.
+Maximum number of connections allowed per connection supervisor.
 
 This is a soft limit. The actual number of connections
 might be slightly above the limit due to concurrency
@@ -91,6 +91,7 @@ opts() = any() | #{
     max_connections   => max_conns(),
     logger            => module(),
     num_acceptors     => pos_integer(),
+    num_conns_sups    => pos_integer(),
     shutdown          => timeout() | brutal_kill,
     socket_opts       => any()
 }
@@ -122,13 +123,18 @@ Maximum allowed time for the `ranch:handshake/1,2` call to finish.
 
 max_connections (1024)::
 
-Maximum number of active connections. Soft limit.
-Use `infinity` to disable the limit entirely.
+Maximum number of active connections per connection supervisor.
+Soft limit. Use `infinity` to disable the limit entirely.
 
 num_acceptors (10)::
 
 Number of processes that accept connections.
 
+num_conns_sups - see below::
+
+Number of processes that supervise connection processes.
+If not specified, defaults to be equal to `num_acceptors`.
+
 shutdown (5000)::
 
 Maximum allowed time for children to stop on listener shutdown.
@@ -149,6 +155,8 @@ Unique name used to refer to a listener.
 
 == Changelog
 
+* *2.0*: The option `max_connections` is now per connection supervisor.
+* *2.0*: The `num_conns_sup` option was added.
 * *2.0*: The `socket` option was removed.
 * *1.6*: The `logger` option was added.
 * *1.6*: The `opt()` type was deprecated in favor of the new `opts()` type.
diff --git a/doc/src/manual/ranch.get_max_connections.asciidoc b/doc/src/manual/ranch.get_max_connections.asciidoc
index 3267c2d..d10c975 100644
--- a/doc/src/manual/ranch.get_max_connections.asciidoc
+++ b/doc/src/manual/ranch.get_max_connections.asciidoc
@@ -2,7 +2,7 @@
 
 == Name
 
-ranch:get_max_connections - Get the max number of connections
+ranch:get_max_connections - Get the max number of connections per connection supervisor
 
 == Description
 
@@ -12,7 +12,7 @@ get_max_connections(Ref :: ranch:ref())
     -> MaxConns :: ranch:max_conns()
 ----
 
-Get the max number of connections.
+Get the max number of connections per connection supervisor.
 
 == Arguments
 
@@ -22,11 +22,16 @@ The listener name.
 
 == Return value
 
-The maximum number of connections is returned.
+The maximum number of connections per connection supervisor
+is returned.
+
+== Changelog
+
+* *2.0*: The maximum number of connections is now per connection supervisor.
 
 == Examples
 
-.Get the max number of connections
+.Get the max number of connections per connection supervisor
 [source,erlang]
 ----
 MaxConns = ranch:get_max_connections(example).
diff --git a/doc/src/manual/ranch.info.asciidoc b/doc/src/manual/ranch.info.asciidoc
index 32cbefb..69a8818 100644
--- a/doc/src/manual/ranch.info.asciidoc
+++ b/doc/src/manual/ranch.info.asciidoc
@@ -32,7 +32,7 @@ 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.
+max_connections:: Maximum number of connections per connection supervisor.
 active_connections:: Number of active connections.
 all_connections:: Number of connections, including those removed from the count.
 transport:: Transport module.
diff --git a/doc/src/manual/ranch.set_max_connections.asciidoc b/doc/src/manual/ranch.set_max_connections.asciidoc
index 2559afe..cc1bb20 100644
--- a/doc/src/manual/ranch.set_max_connections.asciidoc
+++ b/doc/src/manual/ranch.set_max_connections.asciidoc
@@ -2,7 +2,7 @@
 
 == Name
 
-ranch:set_max_connections - Set the max number of connections
+ranch:set_max_connections - Set the max number of connections per connection supervisor
 
 == Description
 
@@ -13,7 +13,7 @@ set_max_connections(Ref      :: ranch:ref(),
     -> ok
 ----
 
-Set the max number of connections.
+Set the max number of connections per connection supervisor.
 
 The change will be applied immediately. If the new value is
 smaller than the previous one, Ranch will wait for the extra
@@ -28,15 +28,19 @@ The listener name.
 
 MaxConns::
 
-The new maximum number of connections.
+The new maximum number of connections per connection supervisor.
 
 == Return value
 
 The atom `ok` is always returned. It can be safely ignored.
 
+== Changelog
+
+* *2.0*: The maximum number of connections is now per connection supervisor.
+
 == Examples
 
-.Set the max number of connections
+.Set the max number of connections per connection supervisor
 [source,erlang]
 ----
 ranch:set_max_connections(example, 10000).