aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide
diff options
context:
space:
mode:
authorjuhlig <[email protected]>2019-07-15 15:52:13 +0200
committerLoïc Hoguin <[email protected]>2019-07-16 16:08:24 +0200
commitf6d1fae69479e18bc7b250d73f19045225030b24 (patch)
treebe356e012cd78011fc9c950f62f062037e446be0 /doc/src/guide
parent1a929ead1268aa948c68d52e0b2f6ff88b299929 (diff)
downloadranch-f6d1fae69479e18bc7b250d73f19045225030b24.tar.gz
ranch-f6d1fae69479e18bc7b250d73f19045225030b24.tar.bz2
ranch-f6d1fae69479e18bc7b250d73f19045225030b24.zip
Update documentation for embedded listeners
Diffstat (limited to 'doc/src/guide')
-rw-r--r--doc/src/guide/embedded.asciidoc41
1 files changed, 20 insertions, 21 deletions
diff --git a/doc/src/guide/embedded.asciidoc b/doc/src/guide/embedded.asciidoc
index 55c018b..28f567b 100644
--- a/doc/src/guide/embedded.asciidoc
+++ b/doc/src/guide/embedded.asciidoc
@@ -5,44 +5,43 @@ in your supervision tree. This allows for greater fault tolerance
control by permitting the shutdown of a listener due to the
failure of another part of the application and vice versa.
+However, just as for non-embedded listeners that were started via
+`ranch:start_listener/5`, it is required that the `ranch` application
+is running before you can start embedded listeners. Furthermore,
+this also means that embedded listeners will restart when `ranch_sup` fails.
+
+WARNING: By using embedded mode, it is possible to start a listener with the same name
+as an already existing listener. This will corrupt the information Ranch
+keeps for that listener, so you should take care to ensure unique listener
+names yourself. A good way to achieve this is by combining the embedded
+listener's name with `?MODULE`, or the name of the application it is used
+in.
+
=== Embedding
To embed Ranch in your application you can simply add the child specs
to your supervision tree. This can all be done in the `init/1` function
of one of your application supervisors.
-Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add `ranch_sup` to your supervision tree, only once,
-regardless of the number of listeners you will use. Then you need to
-add the child specs for each listener.
-
Ranch has a convenience function for getting the listeners child specs
called `ranch:child_spec/5`, that works like `ranch:start_listener/5`,
except that it doesn't start anything, it only returns child specs.
-As for `ranch_sup`, the child spec is simple enough to not require a
-convenience function.
-
-The following example adds both `ranch_sup` and one listener to another
-application's supervision tree.
+The following example adds one listener to another application's
+supervision tree.
.Embed Ranch directly in your supervision tree
[source,erlang]
----
init([]) ->
- RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []},
- permanent, 5000, supervisor, [ranch_sup]},
- ListenerSpec = ranch:child_spec(echo, 100,
- ranch_tcp, [{port, 5555}],
+ ListenerSpec = ranch:child_spec({?MODULE, echo},
+ ranch_tcp, #{socket_opts => [{port, 5555}]},
echo_protocol, []
),
- {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}.
+ {ok, {#{}, [ListenerSpec]}}.
----
-Remember, you can add as many listener child specs as needed, but only
-one `ranch_sup` spec!
-
-It is recommended that your architecture makes sure that all listeners
-are restarted if `ranch_sup` fails. See the Ranch internals chapter for
-more details on how Ranch does it.
+Embedded listeners cannot be stopped via `ranch:stop_listener/1`. Instead,
+are to be stopped as part of the shutdown of your application's supervison
+tree.