Convert the documentation to Asciidoc

1 files changed, 48 insertions, 0 deletions

diff --git a/doc/src/guide/embedded.asciidoc b/doc/src/guide/embedded.asciidoc
new file mode 100644
index 0000000..593a807
--- /dev/null
+++ b/doc/src/guide/embedded.asciidoc
@@ -0,0 +1,48 @@
+== Embedded mode
+
+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.
+
+.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}],
+		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.