ranch:set_transport_options(3)

Name

ranch:set_transport_options - Set the transport options

Description

set_transport_options(Ref       :: ranch:ref(),
                      TransOpts :: ranch:opts())
    -> ok | {error, Reason :: term()}

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 ranch:get_transport_options(3), update them and then set them back using this function.

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
    • post_listen_callback
    • socket_opts
  • only when the entire listener is restarted:
    • connection_type
    • num_conns_sups
    • logger

Arguments

Ref

The listener name.

TransOpts

The new transport options.

Return value

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.

Examples

Set the transport options
Ref = example,

ok = ranch:suspend_listener(Ref),
ok = ranch:set_transport_options(Ref, TransOpts),
ok = ranch:resume_listener(Ref).
Update the listener TCP port within the `socket_opts` transport option
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

ranch:suspend_listener(3), ranch:resume_listener(3), ranch:get_transport_options(3), ranch:set_max_connections(3), ranch:set_protocol_options(3), ranch(3)

Ranch 2.1 Function Reference

Navigation

Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.