From 4a1d16242c6fa9865fd7499d301d90b9ca65d6b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Viktor=20S=C3=B6derqvist?= Date: Thu, 3 Dec 2020 09:34:57 +0100 Subject: Clarify {get,set}_{protocol,transport}_options docs Clarifications and examples. --- doc/src/manual/ranch.get_transport_options.asciidoc | 7 ++++++- doc/src/manual/ranch.set_protocol_options.asciidoc | 13 +++++++++++++ doc/src/manual/ranch.set_transport_options.asciidoc | 20 ++++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/doc/src/manual/ranch.get_transport_options.asciidoc b/doc/src/manual/ranch.get_transport_options.asciidoc index 438df90..0214e0f 100644 --- a/doc/src/manual/ranch.get_transport_options.asciidoc +++ b/doc/src/manual/ranch.get_transport_options.asciidoc @@ -9,7 +9,7 @@ ranch:get_transport_options - Get the current transport options [source,erlang] ---- get_transport_options(Ref :: ranch:ref()) - -> TransOpts :: any() + -> TransOpts :: ranch:transport_opts(any()) ---- Get the current transport options. @@ -24,6 +24,11 @@ The listener name. The current transport options are returned. +If the transport options were specified as only socket options (not a map) using +link:man:ranch:start_listener(3)[ranch:start_listener(3)] or +link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], they +are returned as `#{socket_opts => SocketOpts}`. + == Examples .Get the current transport options diff --git a/doc/src/manual/ranch.set_protocol_options.asciidoc b/doc/src/manual/ranch.set_protocol_options.asciidoc index 1851fab..36370c8 100644 --- a/doc/src/manual/ranch.set_protocol_options.asciidoc +++ b/doc/src/manual/ranch.set_protocol_options.asciidoc @@ -18,6 +18,11 @@ Set the protocol options. The change will be applied immediately for all new connections. Old connections will not receive the new options. +Note that the complete set of protocol options is replaced. To update a subset +of the options, it is recommended to get the current protocol options using +link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)], update +them and then set them back using this function. + == Arguments Ref:: @@ -40,6 +45,14 @@ The atom `ok` is always returned. It can be safely ignored. ranch:set_protocol_options(example, ProtoOpts). ---- +.Update some of the protocol options +[source,erlang] +---- +ProtoOpts0 = ranch:get_protocol_options(example), +ProtoOpts = ProtoOpts0#{request_timeout => 2000}, +ranch:set_protocol_options(example, ProtoOpts). +---- + == See also link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)], diff --git a/doc/src/manual/ranch.set_transport_options.asciidoc b/doc/src/manual/ranch.set_transport_options.asciidoc index 146f21e..8c2eacb 100644 --- a/doc/src/manual/ranch.set_transport_options.asciidoc +++ b/doc/src/manual/ranch.set_transport_options.asciidoc @@ -15,6 +15,11 @@ set_transport_options(Ref :: ranch:ref(), Set the transport options. +The complete set of transport options is replaced. To update a subset of the +transport options, it is recommended to get the current transport options using +link:man:ranch:get_transport_options(3)[ranch:get_transport_options(3)], update +them and then set them back using this function. + Changes to the following options will take effect... * immediately: @@ -66,6 +71,21 @@ ok = ranch:set_transport_options(Ref, TransOpts), ok = ranch:resume_listener(Ref). ---- +.Update the listener TCP port within the `socket_opts` transport option +[source,erlang] +---- +Ref = example, + +TransOpts0 = ranch:get_transport_options(Ref), +#{socket_opts = SocketOpts0} = TransOpts0, +SocketOpts = [{port, 12345}|proplists:delete(port, SocketOpts0)], +TransOpts = TransOpts0#{socket_opts = SocketOpts}, + +ok = ranch:suspend_listener(Ref), +ok = ranch:set_transport_options(Ref, TransOpts), +ok = ranch:resume_listener(Ref). +---- + == See also link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], -- cgit v1.2.3