= ranch:start_listener(3)
== Name
ranch:start_listener - Start a listener
== Description
[source,erlang]
----
start_listener(Ref :: ranch_ref(),
Transport :: module(),
TransOpts :: ranch:opts(),
Protocol :: module(),
ProtoOpts :: any())
-> {ok, ListenerPid :: pid()}
| {error, any()}
----
Start a listener.
A listener is a set of processes that accepts and manages
connections using the given transport and protocol modules.
== Arguments
Ref::
The listener name is used to refer to this listener in
future calls, for example when stopping it or 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
link:man:ranch_transport(3)[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.
+
Socket options may be given directly if there are no
Ranch-specific options.
+
The available options for the built-in Ranch transports
are documented in the link:man:ranch_tcp(3)[ranch_tcp(3)]
and link:man:ranch_ssl(3)[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
link:man:ranch_protocol(3)[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
An ok tuple is returned on success. It contains the pid of
the top-level supervisor for the listener.
An error tuple is returned on error. The error reason may
be any Erlang term.
A common error is `eaddrinuse`. It indicates that the port
configured for Ranch is already in use.
== Changelog
* *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
.Start a listener
[source,erlang]
----
{ok, _} = ranch:start_listener(example,
ranch_tcp, [{port, 8080}],
cowboy_http2, #{}
).
----
.Start a listener with Ranch-specific options
[source,erlang]
----
{ok, _} = ranch:start_listener(example,
ranch_tcp, #{
num_acceptors => 75,
socket_opts => [{port, 8080}]
},
cowboy_http2, #{}
).
----
.Start a listener on a random port
[source,erlang]
----
Ref = example,
{ok, _} = ranch:start_listener(Ref,
ranch_tcp, #{},
cowboy_http2, #{}
),
Port = ranch:get_port(Ref).
----
== See also
link:man:ranch:stop_listener(3)[ranch:stop_listener(3)],
link:man:ranch:child_spec(3)[ranch:child_spec(3)],
link:man:ranch(3)[ranch(3)],
link:man:ranch_tcp(3)[ranch_tcp(3)],
link:man:ranch_ssl(3)[ranch_ssl(3)],
link:man:ranch_transport(3)[ranch_transport(3)],
link:man:ranch_protocol(3)[ranch_protocol(3)]
