A behaviour module for implementing supervision functionality.

A supervisor is a process which supervises other processes, which we refer to as child processes. Supervisors are used to build a hierarchical process structure called a supervision tree. Supervision trees are a nice way to structure fault-tolerant applications.

A supervisor implemented using this module has a standard set of interface functions and includes functionality for tracing and error reporting. It also fits into a supervision tree.

Examples

In order to define a supervisor, we need to first define a child process that is going to be supervised. In order to do so, we will define a GenServer that represents a stack:

defmodule Stack do
  use GenServer

  def start_link(state, opts \\ []) do
    GenServer.start_link(__MODULE__, state, opts)
  end

  def handle_call(:pop, _from, [h | t]) do
    {:reply, h, t}
  end

  def handle_cast({:push, h}, t) do
    {:noreply, [h | t]}
  end
end

We can now define our supervisor and start it as follows:

# Import helpers for defining supervisors
import Supervisor.Spec

# Supervise the Stack server which will be started with
# two arguments. The initial stack, [:hello], and a
# keyword list containing the GenServer options that
# set the registered name of the server to MyStack.
children = [
  worker(Stack, [[:hello], [name: MyStack]])
]

# Start the supervisor with our child
{:ok, pid} = Supervisor.start_link(children, strategy: :one_for_one)

# There is one child worker started
Supervisor.count_children(pid)
#=> %{active: 1, specs: 1, supervisors: 0, workers: 1}

Notice that when starting the GenServer, we are registering it with name MyStack, which allows us to call it directly and get what is on the stack:

GenServer.call(MyStack, :pop)
#=> :hello

GenServer.cast(MyStack, {:push, :world})
#=> :ok

GenServer.call(MyStack, :pop)
#=> :world

However, there is a bug in our stack server. If we call :pop and the stack is empty, it is going to crash because no clause matches:

GenServer.call(MyStack, :pop)
** (exit) exited in: GenServer.call(MyStack, :pop, 5000)

Luckily, since the server is being supervised by a supervisor, the supervisor will automatically start a new one, with the initial stack of [:hello]:

GenServer.call(MyStack, :pop)
#=> :hello

Supervisors support different strategies; in the example above, we have chosen :one_for_one. Furthermore, each supervisor can have many workers and supervisors as children, each of them with their specific configuration, shutdown values, and restart strategies.

The rest of this documentation will cover supervision strategies; also read the documentation for the Supervisor.Spec module to learn about the specification for workers and supervisors.

Module-based supervisors

In the example above, a supervisor was started by passing the supervision structure to start_link/2. However, supervisors can also be created by explicitly defining a supervision module:

defmodule MyApp.Supervisor do
  # Automatically imports Supervisor.Spec
  use Supervisor

  def start_link do
    Supervisor.start_link(__MODULE__, [])
  end

  def init([]) do
    children = [
      worker(Stack, [[:hello]])
    ]

    # supervise/2 is imported from Supervisor.Spec
    supervise(children, strategy: :one_for_one)
  end
end

You may want to use a module-based supervisor if:

• You need to perform some particular action on supervisor initialization, like setting up an ETS table.

• You want to perform partial hot-code swapping of the tree. For example, if you add or remove children, the module-based supervision will add and remove the new children directly, while dynamic supervision requires the whole tree to be restarted in order to perform such swaps.

Strategies

Supervisors support different supervision strategies (through the :strategy option, as seen above):

• :one_for_one - if a child process terminates, only that process is restarted.

• :one_for_all - if a child process terminates, all other child processes are terminated and then all child processes (including the terminated one) are restarted.

• :rest_for_one - if a child process terminates, the “rest” of the child processes, i.e., the child processes after the terminated one in start order, are terminated. Then the terminated child process and the rest of the child processes are restarted.

• :simple_one_for_one - similar to :one_for_one but suits better when dynamically attaching children. This strategy requires the supervisor specification to contain only one child. Many functions in this module behave slightly differently when this strategy is used.

Simple one for one

The :simple_one_for_one supervisor is useful when you want to dynamically start and stop supervised children. For example, imagine you want to dynamically create multiple stacks. We can do so by defining a :simple_one_for_one supervisor:

# Import helpers for defining supervisors
import Supervisor.Spec

# This time, we don't pass any argument because
# the argument will be given when we start the child
children = [
  worker(Stack, [], restart: :transient)
]

# Start the supervisor with our one child as a template
{:ok, sup_pid} = Supervisor.start_link(children, strategy: :simple_one_for_one)

# No child worker is active yet until start_child is called
Supervisor.count_children(sup_pid)
#=> %{active: 0, specs: 1, supervisors: 0, workers: 0}

There are a couple differences here:

• the simple one for one specification can define only one child which works as a template for when we call start_child/2

• we have defined the child to have a restart strategy of :transient. This means that, if the child process exits due to a :normal, :shutdown, or {:shutdown, term} reason, it won’t be restarted. This is useful as it allows our workers to politely shutdown and be removed from the :simple_one_for_one supervisor, without being restarted. You can find more information about restart strategies in the documentation for the Supervisor.Spec module

With the supervisor defined, let’s dynamically start stacks:

{:ok, pid} = Supervisor.start_child(sup_pid, [[:hello, :world], []])
GenServer.call(pid, :pop) #=> :hello
GenServer.call(pid, :pop) #=> :world

{:ok, pid} = Supervisor.start_child(sup_pid, [[:something, :else], []])
GenServer.call(pid, :pop) #=> :something
GenServer.call(pid, :pop) #=> :else

Supervisor.count_children(sup_pid)
#=> %{active: 2, specs: 1, supervisors: 0, workers: 2}

Exit reasons

From the example above, you may have noticed that the :transient restart strategy for the worker does not restart the child in case it exits with reason :normal, :shutdown or {:shutdown, term}.

So one may ask: which exit reason should I choose when exiting my worker? There are three options:

• :normal - in such cases, the exit won’t be logged, there is no restart in transient mode, and linked processes do not exit

• :shutdown or {:shutdown, term} - in such cases, the exit won’t be logged, there is no restart in transient mode, and linked processes exit with the same reason unless they’re trapping exits

• any other term - in such cases, the exit will be logged, there are restarts in transient mode, and linked processes exit with the same reason unless they’re trapping exits

Name registration

A supervisor is bound to the same name registration rules as a GenServer. Read more about these rules in the documentation for GenServer.