From f13ea025251571cbdbae069c2abdb5e29c2410af Mon Sep 17 00:00:00 2001
From: juhlig <j.uhlig@mailingwork.de>
Date: Tue, 2 Jul 2019 12:04:28 +0200
Subject: Set transport options without suspend

Lift the restriction that a listener must be suspended before
transport options can be changed.

* Changes to the `max_connections`, `handshake_timeout` and `shutdown`
  options will take effect immediately.
* Changes to the `num_acceptors`, `num_listen_sockets` and `socket_opts`
  options will take effect when a listener is suspended and resumed, or
  when the acceptors supervisor restarts.
* Changes to the `num_conns_sups` and `connection_type` options will only
  take effect when the connections super-supervisor restarts.
* Changes to the `logger` option will never take effect, unless a listener
  is stopped and started with fresh transport options.

The fetching and handing down of transport options changes with this
commit, to ensure consistency between the individual components in the
hierarchy.

* The `num_acceptors` option is handed down from the listener supervisor to
  the acceptors supervisor in the child spec, while the `num_listen_sockets`
  and `socket_opts` options are read inside the acceptors supervisor itself.
  This way, the `num_acceptors` option will only take effect when the listener
  supervisor restarts, whereas the other two options will take effect
  when acceptors supervisor restarts. This commit moves the fetching of
  the `num_acceptors` option into the acceptors supervisor as well.
* The `logger` option is read in multiple places throughout the hierarchy.
  This way it may happen that processes that suffered a crash and restart
  may use a different logger than other processes that did not. This commit
  reads the `logger` from the transport options given to the listener supervisor
  start function, and hands it down from there.
* The `connection_type` option is read individually by each connection supervisor.
  This way, a restart of an individual connection supervisor may cause them
  to use a different connection type than the others. This commit reads the
  transport options in the connections super-supervisor, and hands them down to
  the individual connections supervisors.
* The `num_conns_sups` is handed down from the listener supervisor to the
  connections super-supervisor. This way, a change to this option will only
  take effect when the listener supervisor restarts. This commit moves
  the fetching of this option inside the connections super-supervisor. This
  change is merely for structural consistency, it is not necessary for operational
  consistency.
---
 doc/src/guide/listeners.asciidoc | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

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

diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 94552ba..df94896 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -358,14 +358,23 @@ Opts = ranch:get_protocol_options(tcp_echo).
 
 === Changing transport options
 
-Ranch allows you to change the transport options of a listener, for
-example to make it listen on a different port.
-
-To change transport options, the listener has to be suspended first.
-Then you are allowed to change the transport options by calling
-`ranch:set_transport_options/2` with the listener name and the new
-transport options as arguments.
-After that, you can resume the listener.
+Ranch allows you to change the transport options of a listener with
+the `ranch:set_transport_options/2` function, for example to change the
+number of acceptors or to make it listen on a different port.
+
+Changes to the following options will take effect...
+
+* immediately:
+** `max_connections`
+** `handshake_timeout`
+** `shutdown`
+* only after the listener has been suspended and resumed:
+** `num_acceptors`
+** `num_listen_sockets`
+** `socket_opts`
+* only when the entire listener is restarted:
+** `num_conns_sups`
+** `logger`
 
 .Changing the transport options
 
-- 
cgit v1.2.3

