diff options
Diffstat (limited to 'guide/embedded.md')
-rw-r--r-- | guide/embedded.md | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/guide/embedded.md b/guide/embedded.md new file mode 100644 index 0000000..82dab75 --- /dev/null +++ b/guide/embedded.md @@ -0,0 +1,50 @@ +Embedded mode +============= + +Purpose +------- + +Embedded mode allows you to insert Ranch listeners directly +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. + +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/6```, that works like ```ranch:start_listener/6```, +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. + +``` erlang +init([]) -> + RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []}, + permanent, 5000, supervisor, [ranch_sup]}, + ListenerSpec = ranch:child_spec(echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] + ), + {ok, {{one_for_one, 10, 10}, [RanchSupSpec, 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. |