ranch:child_spec(3)

NAME

ranch:child_spec - Build child specifications for a new listener

DESCRIPTION
    child_spec(Ref       :: ranch_ref(),
               Transport :: module(),
               TransOpts :: ranch:opts(),
               Protocol  :: module(),
               ProtoOpts :: any())
        -> supervisor:child_spec()

Build child specifications for a new listener which can be embedded directly in an application's supervision tree.

The actual listener is placed under a supervisor which monitors ranch_server via a proxy process and will restart the listener if ranch_server crashes.

ARGUMENTS

Ref
    The listener name is used to refer to this listener in future calls, for example when updating the configuration.

    It can be any Erlang term. An atom is generally good enough, for example api, my_app_clear or my_app_tls.

Transport
    The transport module that will be used by Ranch to accept connections and that will be passed to the protocol module along with the socket.

    The interface of the transport module is documented in the ranch_transport(3) manual.

TransportOpts
    Transport options include the Ranch-specific options and the socket options. The listener's port number must be defined in the socket options.

    The available options for the built-in Ranch transports are documented in the ranch_tcp(3) and ranch_ssl(3) manuals.

Protocol
    The protocol module that will be used by Ranch after the connection has been accepted.

    The interface of the protocol module is documented in the ranch_protocol(3) manual.

ProtocolOpts
    The protocol options given when calling the protocol module. Please consult the documentation of the protocol module you are using for more details.

RETURN VALUE

Child specifications are returned.

CHANGELOG
    • 2.0: The actual listener is placed under a supervisor in order to restart the listener if ranch_server crashes.
    • 2.0: The TransOpts argument must no longer contain Ranch-specific options if given as a list. Use a map.
    • 1.4: The NumAcceptors argument was moved to the transport options.

EXAMPLES

Embed a listener
    -behavior(supervisor).

    init(_) ->
        {ok, {#{strategy => one_for_one}, [
            ranch:child_spec(echo,
                ranch_tcp, [{port, 5555}],
                echo_protocol, []
            )
        ]}}.

SEE ALSO

ranch:start_listener(3), ranch:stop_listener(3), ranch(3), ranch_tcp(3), ranch_ssl(3), ranch_transport(3), ranch_protocol(3)