From f6d1fae69479e18bc7b250d73f19045225030b24 Mon Sep 17 00:00:00 2001 From: juhlig Date: Mon, 15 Jul 2019 15:52:13 +0200 Subject: Update documentation for embedded listeners --- doc/src/guide/embedded.asciidoc | 41 ++++++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 21 deletions(-) (limited to 'doc/src') 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. -- cgit v1.2.3