Functions for implementing a parent process.

A parent process is a process that manages the lifecycle of its children. Typically the simplest approach is to use higher-level abstractions, such as Parent.Supervisor or Parent.GenServer. The common behaviour for every parent process is implemented in this module, and therefore it is described in this document.

Overview

A parent process has the following properties:

1. It traps exits and uses the shutdown: :infinity shutdown strategy.
2. It keeps track of its children.
3. It presents itself to the rest of the OTP as a supervisor, which means that generic code walking the supervision tree, such as OTP release handler, will also iterate the parent's subtree.
4. Before terminating, it stops its children synchronously, in the reverse startup order.

You can interact with the parent process from other processes using functions from the Parent.Client module. If you want to manipulate the parent from the inside, you can use the functions from this module.

Initialization

A parent process has to be initialized using initialize/1. This function takes the following initialization options:

• :max_restarts and :max_seconds - same as with Supervisor, with the same defaults
• :registry? - If true, the parent will manage its own ETS-based child registry. See the "Child discovery" section for details.

When using higher-level abstractions, these options are typically passed throguh start functions, such as Parent.Supervisor.start_link/2.

Child specification

Child specification describes how the parent starts and manages a child. This specification if passed to functions such as start_child/1, Parent.Client.start_child/2, or Parent.Supervisor.start_link/2 to start a child process.

The specification is a map which is a superset of the Supervisor child specifications. All the fields that are shared with Supervisor have the same effect.

It's worth noting that the :id field is optional. If not provided, the child will be anonymous, and you can only manage it via its pid. Therefore, the minimum required child specification is %{start: mfa_or_zero_arity_fun}.

Also, just like with Supervisor, you can provide module | {module, arg} when starting a child. See Supervisor.child_spec/1 for details.

To modify a child specification, Parent.child_spec/2 can be used.

Child restart

The :restart option can have following values:

• :permanent - A child is automatically restarted if it stops. This is the default value.
• :transient - A child is automatically restarted only if it exits abnormally.
• :with_dep - A child is restarted only if its dependency is restarted.
• :temporary - A child is not automatically restarted.

Maximum restart frequency

Similarly to Supervisor, a parent process keeps track of the amount of restarts, and self-terminates if maximum threshold (defaults to 3 restarts in 5 seconds) is exceeded.

In addition, you can provide child specific thresholds by including :max_restarts and :max_seconds options in child specification. Finally, note that :max_restarts can be set to :infinity (both for the parent and each child). This can be useful if you want to disable the parent global limit, and use child-specific limits.

Bound children

You can bind the lifecycle of each child to the lifecycles of its older siblings. This is roughly similar to the :rest_for_one supervisor strategy.

For example, if you want to start two children, consumer and producer, and bind the producer's lifecycle to the consumer, you need the following child specifications:

consumer_spec = %{
  id: :consumer,
  # ...
}

producer_spec = %{
  id: :producer,
  binds_to: [:consumer]
}

This will make sure that if the consumer stops, the producer is taken down as well.

For this to work, you need to start the consumer before the producer. In other words, a child can only be bound to its older siblings.

It's worth noting that bindings are transitive. If a child A is bound to the child B, which is in turns bound to child C, then child A also depends on child C. If child C stops, B and A will be stopped to.

Finally, because of binding semantics (see Lifecycle dependency consequences), a child can only be bound to a sibling with the same or stronger restart option, where restart strengths can be defined as permanent > transient > with_dep > temporary. So for example, a permanent child can't be bound to a temporary child.

Shutdown groups

A shutdown group is a mechanism that roughly emulates the :one_for_all supervisor strategy. For example, to set up a two-way lifecycle dependency between the consumer and the producer, we can use the following specifications:

consumer_spec = %{
  id: :consumer,
  shutdown_group: :consumer_and_producer
  # ...
}

producer_spec = %{
  id: :producer,
  shutdown_group: :consumer_and_producer
}

In this case, when any child of the group terminates, the other children will be taken down as well.

All children belonging to the same shutdown group must use the same :restart option.

Note that a child can be a member of some shutdown group, and bound to other older siblings.

Lifecycle dependency consequences

As has been mentioned, a lifecycle dependency means that a child is taken down when its dependency stops. This will happen irrespective of how the child has been stopped. Even if you manually stop the child using functions such as shutdown_child/1 or Parent.Client.shutdown_child/2, the siblings bound to it will be taken down.

In general, parent doesn't permit the state which violates binding settings. If the process A is bound to the process B, you can never reach the state where A is running but B isn't. Of course, since things are taking place concurrently, such state might briefly exists until parent is able to shutdown all bound processes.

Restart flow

Process restarts happen automatically, if a permanent child stops or if a transient child crashes. They can also happen manually, when you invoke restart_child/1 or if you're manually returning terminated non-restarted children with the function return_children/2. In all these situations, the flow is the same.

When a child stops, parent will take down all the siblings bound to it, and then attempt to restart the child and its non-temporary siblings. This is done by starting processes synchronously, one by one, in their startup order. If all processes are started successfully, restart has succeeded.

If some process fails to start, the parent won't try to start younger siblings. If some of the successfully started children are bound to non-started siblings, they will be taken down as well. This happens because parent won't permit the state which doesn't conform to the binding requirements.

Therefore, a restart may partially succeed, with some children not being started. In this case, the parent will retry to restart the remaining children.

An attempt to restart a child which failed to restart is considered as a crash and contributes to the restart intensity. Thus, if a child repeatedly fails to restart, the parent will give up at some point, according to restart intensity settings.

When the children are restarted, they will be started in the original startup order. The restarted children keep their original startup order with respect to non-restarted children. For example, suppose that four children are running: A, B, C, and D, and children B and D are restarted. If the parent process then stops, it will take the children down in the order D, C, B, and A.

Finally, it's worth noting that if termination of one child causes the restart of multiple children, parent will treat this as a single restart event when calculating the restart frequency and considering possible self-termination.

Child timeout

You can optionally include the :timeout option in the child specification to ask the parent to terminate the child if it doesn't stop in the given time. In this case, the child's shutdown strategy is ignore, and the child will be forcefully terminated (using the :kill exit signal).

A non-temporary child which timeouts will be restarted.

Child discovery

Children can be discovered by other processes using functions such as Parent.Client.child_pid/2, or Parent.Client.children/1. By default, these functions will perform a synchronous call into the parent process. This should work fine as long as the parent is not pressured by various events, such as frequent children stopping and starting, or some other custom logic.

In such cases you can consider setting the registry? option to true when initializing the parent process. When this option is set, parent will create an ETS table which will be used by the discovery functions.

In addition, parent supports maintaining the child-specific meta information. You can set this information by providing the :meta field in the child specification, update it through functions such as update_child_meta/2 or Parent.Client.update_child_meta/3, and query it through Parent.Client.child_meta/2.

Ignored child

If a child start function returns :ignore, the parent assumes that the child process is not started. This can be useful to defer the decision about starting some processes to the latest possible moment.

In this case, the parent process will treat the child as successfully started. The corresponding entry for the child will exist in internal data structure of the parent, and the child will be included in result of the functions such as children/0, with its pid set to :undefined.

If an ignored child is bound to a started child and that child is restarted, the ignored child will be restarted too.

For children which are started dynamically on-demand, this might lead to memory leaks. In such cases you can include keep_ignored?: false in the childspec to instruct the supervisor to avoid keeping the child entry if the start function returns :ignore.

Building custom parent processes

If available parent behaviours don't fit your purposes, you can consider building your own behaviour or a concrete parent process. In this case, the functions of this module will provide the necessary plumbing.

The basic idea is presented in the following sketch:

defp init_process do
  Parent.initialize(parent_opts)
  start_some_children()
  loop()
end

defp loop() do
  receive do
    msg ->
      case Parent.handle_message(msg) do
        # parent handled the message
        :ignore -> loop()

        # parent handled the message and returned some useful information
        {:stopped_children, stopped_children} -> handle_stopped_children(stopped_children)

        # not a parent message
        nil -> custom_handle_message(msg)
      end
  end
end

More specifically, to build a parent process you need to do the following:

1. Invoke initialize/0 when the process is started.
2. Use functions such as start_child/1 to work with child processes.
3. When a message is received, invoke handle_message/1 before handling the message yourself.
4. If you receive a shutdown exit message from your parent, stop the process.
5. Before terminating, invoke shutdown_all/1 to stop all the children.
6. Use :infinity as the shutdown strategy for the parent process, and :supervisor for its type.
7. If the process is a GenServer, handle supervisor calls (see supervisor_which_children/0 and supervisor_count_children/0).
8. Implement format_status/2 (see Parent.GenServer for details) where applicable.

If the parent process is powered by a non-interactive code (e.g. Task), make sure to receive messages sent to that process, and handle them properly (see points 3 and 4).

You can take a look at the code of Parent.GenServer for specific details.