2 files changed, 98 insertions, 0 deletions
diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 97afa22..21a6838 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -91,6 +91,34 @@ named `tcp_echo`. We can now stop it.
 [source,erlang]
 ranch:stop_listener(tcp_echo).
 
+=== Suspending and resuming a listener
+
+Listeners can be suspended and resumed by calling
+`ranch:suspend_listener/1` and `ranch:resume_listener/1`,
+respectively, with the name of the listener as argument.
+
+Suspending a listener will cause it to stop listening and not accept
+new connections, but existing connection processes will not be stopped.
+
+.Suspending a listener
+
+[source,erlang]
+ranch:suspend_listener(tcp_echo).
+
+Resuming a listener will cause it to start listening and accept new
+connections again.
+It is worth mentioning, however, that if the listener is configured
+to listen on a random port, it will listen on a different port than
+before it was suspended.
+
+.Resuming a listener
+
+[source,erlang]
+ranch:resume_listener(tcp_echo).
+
+Whether a listener is currently running or suspended can be queried
+by calling `ranch:get_status/1` with the listener name as argument.
+
 === Default transport options
 
 By default the socket will be set to return `binary` data, with the
@@ -296,6 +324,30 @@ calling `ranch:get_protocol_options/1`.
 [source,erlang]
 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.
+
+.Changing the transport options
+
+[source,erlang]
+ranch:set_transport_options(tcp_echo, NewOpts).
+
+You can retrieve the current transport options by calling
+`ranch:get_transport_options/1`.
+
+.Retrieving the current transport options
+
+[source,erlang]
+Opts = ranch:get_transport_options(tcp_echo).
+
 === Obtaining information about listeners
 
 Ranch provides two functions for retrieving information about the
diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index e0244c8..b442f88 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -114,6 +114,19 @@ ProtoOpts = any():: Current protocol options.
 
 Return the protocol options set for the given listener.
 
+=== get_status(Ref) -> running | suspended
+
+Ref = ref():: Listener name.
+
+Return the status of the given listener.
+
+=== get_transport_options(Ref) -> ProtoOpts
+
+Ref = ref():: Listener name.
+TransOpts = any():: Current transport options.
+
+Return the transport options set for the given listener.
+
 === info() -> [{Ref, [{Key, Value}]}]
 
 Ref = ref():: Listener name.
@@ -155,6 +168,16 @@ without sacrificing the latency of the system.
 
 This function may only be called from a connection process.
 
+=== resume_listener(Ref) -> ok
+
+Ref = ref():: Listener name.
+
+Resume the given listener if it is suspended.
+If the listener is already running, nothing will happen.
+
+The listener will be started with the transport options
+currently set for it.
+
 === set_max_connections(Ref, MaxConns) -> ok
 
 Ref = ref():: Listener name.
@@ -176,6 +199,18 @@ Set the protocol options for the given listener.
 The change will be applied immediately for all new connections.
 Old connections will not receive the new options.
 
+=== set_transport_options(Ref, TransOpts) -> ok | {error, running}
+
+Ref = ref():: Listener name.
+ProtoOpts = any():: New transport options.
+
+Set the transport options for the given listener.
+
+The listener must be suspended for this call to succeed.
+If the listener is running, `{error, running}` will be returned.
+
+The change will take effect when the listener is being resumed.
+
 === start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> {ok, pid()} | {error, badarg}
 
 Ref = ref():: Listener name.
@@ -207,3 +242,14 @@ connection processes or give them some time to stop properly.
 
 This function does not return until the listener is
 completely stopped.
+
+=== suspend_listener(Ref) -> ok
+
+Ref = ref():: Listener name.
+
+Suspend the given listener if it is running.
+If the listener is already suspended, nothing will happen.
+
+The listener will stop listening and accepting connections by
+closing the listening port, but will not stop running connection
+processes.