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.


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.

Embed Ranch directly in your supervision tree
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.

Ranch 1.6 User Guide


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.