1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
= 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)]
|
