diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/src/guide/listeners.asciidoc | 52 | ||||
-rw-r--r-- | doc/src/manual/ranch.asciidoc | 46 |
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. |