aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/ranch.child_spec.asciidoc
blob: bd6c056c107fb2084b76795749c8a848f4b424c5 (plain) (blame)
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
= ranch:child_spec(3)

== Name

ranch:child_spec - Build child specifications for a new listener

== Description

[source,erlang]
----
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
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

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
[source,erlang]
----
-behavior(supervisor).

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

== See also

link:man:ranch:start_listener(3)[ranch:start_listener(3)],
link:man:ranch:stop_listener(3)[ranch:stop_listener(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)]