DynamicSupervisor behaviour

A supervisor that starts children dynamically.

The Supervisor module was designed to handle mostly static children that are started in the given order when the supervisor starts. A DynamicSupervisor starts with no children. Instead, children are started on demand via start_child/2. When a dynamic supervisor terminates, all children are shutdown at the same time, with no guarantee of ordering.

Examples

A dynamic supervisor is started with no children, only with the supervision strategy (the only strategy currently supported is :one_for_one):

{:ok, sup} = DynamicSupervisor.start_link(strategy: :one_for_one)

Once the dynamic supervisor is running, we can start children with start_child/2, which receives a child specification:

{:ok, agent1} = DynamicSupervisor.start_child(sup, {Agent, fn -> %{} end})
Agent.update(agent1, &Map.put(&1, :key, "value"))
Agent.get(agent1, & &1)
#=> %{key: "value"}

{:ok, agent2} = DynamicSupervisor.start_child(sup, {Agent, fn -> %{} end})
Agent.get(agent2, & &1)
#=> %{}

DynamicSupervisor.count_children(sup)
#=> %{active: 2, specs: 2, supervisors: 0, workers: 2}

Module-based supervisors

Similar to Supervisor, dynamic supervisors also support module-based supervisors.

defmodule MyApp.DynamicSupervisor do
  # Automatically defines child_spec/1
  use DynamicSupervisor

  def start_link(arg) do
    DynamicSupervisor.start_link(__MODULE__, arg, name: __MODULE__)
  end

  def init(_arg) do
    DynamicSupervisor.init(strategy: :one_for_one)
  end
end

See the Supervisor docs for a discussion of when you may want to use module-based supervisors.

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.

Summary

Types

init_option()

Options given to start_link/2 and init/1

option()

Option values used by the start* functions

options()

Options used by the start* functions

strategy()

Supported strategies

sup_flags()

Functions

count_children(supervisor)

Returns a map containing count values for the supervisor

start_child(supervisor, child_spec)

Dynamically adds a child specification to supervisor and starts that child

start_link(options)

Starts a supervisor with the given options

start_link(mod, args, opts \\ [])

Starts a module-based supervisor process with the given module and arg

terminate_child(supervisor, pid)

Terminates the given child identified by child id

which_children(supervisor)

Returns a list with information about all children

Callbacks

init(args)

Callback invoked to start the supervisor and during hot code upgrades

Types

init_option()

init_option() ::
  {:strategy, strategy()} |
  {:max_restarts, non_neg_integer()} |
  {:max_seconds, pos_integer()} |
  {:max_children, non_neg_integer() | :infinity} |
  {:extra_arguments, [term()]}

Options given to start_link/2 and init/1

option()

option() :: {:name, Supervisor.name()} | init_option()

Option values used by the start* functions

options()

options() :: [option(), ...]

Options used by the start* functions

strategy()

strategy() :: :one_for_one

Supported strategies

sup_flags()

sup_flags()

Functions

count_children(supervisor)

count_children(Supervisor.supervisor()) :: %{specs: non_neg_integer(), active: non_neg_integer(), supervisors: non_neg_integer(), workers: non_neg_integer()}

Returns a map containing count values for the supervisor.

The map contains the following keys:

• :specs - always 1 as dynamic supervisors have a single specification

• :active - the count of all actively running child processes managed by this supervisor

• :supervisors - the count of all supervisors whether or not the child process is still alive

• :workers - the count of all workers, whether or not the child process is still alive

start_child(supervisor, child_spec)

start_child(Supervisor.supervisor(), :supervisor.child_spec() | {module(), term()} | module()) :: Supervisor.on_start_child()

Dynamically adds a child specification to supervisor and starts that child.

child_spec should be a valid child specification. The child process will be started as defined in the child specification.

If the child process start function returns {:ok, child} or {:ok, child, info}, then child specification and PID are added to the supervisor and this function returns the same value.

If the child process start function returns :ignore, then no child is added to the supervision tree and this function returns :ignore too.

If the child process start function returns an error tuple or an erroneous value, or if it fails, the child specification is discarded and this function returns {:error, error} where error is a term containing information about the error and child specification.

If the supervisor already has N children in a way that N exceeds the amount of :max_children set on the supervisor initialization (see init/1), then this function returns {:error, :max_children}.

start_link(options)

start_link(options()) :: Supervisor.on_start()

Starts a supervisor with the given options.

The :strategy is a required option and the currently supported value is :one_for_one. The remaining options can be found in the init/1 docs.

The :name option can also be used to register a supervisor name. The supported values are described under the “Name registration” section in the GenServer module docs.

If the supervisor is successfully spawned, this function returns {:ok, pid}, where pid is the PID of the supervisor. If the supervisor is given a name and a process with the specified name already exists, the function returns {:error, {:already_started, pid}}, where pid is the PID of that process.

Note that a supervisor started with this function is linked to the parent process and exits not only on crashes but also if the parent process exits with :normal reason.

start_link(mod, args, opts \\ [])

start_link(module(), term(), GenServer.options()) :: Supervisor.on_start()

Starts a module-based supervisor process with the given module and arg.

To start the supervisor, the init/1 callback will be invoked in the given module, with arg as its argument. The init/1 callback must return a supervisor specification which can be created with the help of the init/1 function.

If the init/1 callback returns :ignore, this function returns :ignore as well and the supervisor terminates with reason :normal. If it fails or returns an incorrect value, this function returns {:error, term} where term is a term with information about the error, and the supervisor terminates with reason term.

The :name option can also be given in order to register a supervisor name, the supported values are described in the “Name registration” section in the GenServer module docs.

terminate_child(supervisor, pid)

terminate_child(Supervisor.supervisor(), pid()) ::
  :ok |
  {:error, :not_found}

Terminates the given child identified by child id.

If successful, this function returns :ok. If there is no process with the given PID, this function returns {:error, :not_found}.

which_children(supervisor)

which_children(Supervisor.supervisor()) :: [{:undefined, pid() | :restarting, :worker | :supervisor, :supervisor.modules()}]

Returns a list with information about all children.

Note that calling this function when supervising a large number of children under low memory conditions can cause an out of memory exception.

This function returns a list of tuples containing:

• id - it is always :undefined for dynamic supervisors

• child - the pid of the corresponding child process or the atom :restarting if the process is about to be restarted

• type - :worker or :supervisor as defined in the child specification

• modules - as defined in the child specification

Callbacks

init(args)

init(args :: term()) :: {:ok, sup_flags()} | :ignore

Callback invoked to start the supervisor and during hot code upgrades.

Developers typically invoke DynamicSupervisor.init/1 at the end of their init callback to return the proper supervision flags.