aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorjuhlig <[email protected]>2019-07-02 12:04:28 +0200
committerjuhlig <[email protected]>2019-07-02 12:04:28 +0200
commitf13ea025251571cbdbae069c2abdb5e29c2410af (patch)
treeab07f973c2558799f9e2ba74279dedc297a78cf2 /doc
parent37e64f50df640803625771bc3655b6db6c351493 (diff)
downloadranch-f13ea025251571cbdbae069c2abdb5e29c2410af.tar.gz
ranch-f13ea025251571cbdbae069c2abdb5e29c2410af.tar.bz2
ranch-f13ea025251571cbdbae069c2abdb5e29c2410af.zip
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.
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/listeners.asciidoc25
-rw-r--r--doc/src/manual/ranch.set_transport_options.asciidoc26
2 files changed, 37 insertions, 14 deletions
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
diff --git a/doc/src/manual/ranch.set_transport_options.asciidoc b/doc/src/manual/ranch.set_transport_options.asciidoc
index cba6ba7..6c349ca 100644
--- a/doc/src/manual/ranch.set_transport_options.asciidoc
+++ b/doc/src/manual/ranch.set_transport_options.asciidoc
@@ -9,16 +9,25 @@ ranch:set_transport_options - Set the transport options
[source,erlang]
----
set_transport_options(Ref :: ranch:ref(),
- TransOpts :: any())
- -> ok | {error, running}
+ TransOpts :: ranch:opts())
+ -> ok | {error, Reason :: term()}
----
Set the transport options.
-The listener must be suspended for this call to succeed.
-If the listener is running, `{error, running}` will be returned.
+Changes to the following options will take effect...
-The change will take effect when the listener resumes.
+* 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`
== Arguments
@@ -32,10 +41,15 @@ The new transport options.
== Return value
-The atom `ok` is always returned. It can be safely ignored.
+The atom `ok` is returned on success.
+
+An error tuple is returned on failure, for example if the given
+transport options contain invalid values.
== Changelog
+* *2.0*: The restriction that the listener must be suspended
+ has been removed.
* *2.0*: The `TransOpts` argument must no longer contain
Ranch-specific options if given as a list. Use a map.