GenServer with parenting capabilities powered by Parent.

This behaviour can be useful in situations where Parent.Supervisor won't suffice.

Example

The following example is roughly similar to a standard callback-based Supervisor:

defmodule MyApp.Supervisor do
  # Automatically defines child_spec/1
  use Parent.GenServer

  def start_link(init_arg),
    do: Parent.GenServer.start_link(__MODULE__, init_arg, name: __MODULE__)

  @impl GenServer
  def init(_init_arg) do
    Parent.start_all_children!(children)
    {:ok, initial_state}
  end
end

The expression use Parent.GenServer will also inject use GenServer into your code. Your parent process is a GenServer, and this behaviour doesn't try to hide it. Except when starting the process, you work with the parent exactly as you work with any GenServer, using the same functions, such as GenServer.call/3, and providing the same callbacks, such as init/1, or handle_call/3.

Interacting with the parent from the outside

You can issue regular GenServer calls and casts, and send messages to the parent, which can be handled by corresponding GenServer callbacks. In addition, you can use functions from the Parent.Client module to manipulate or query the parent state from other processes. As a good practice, it's advised to wrap such invocations in the module which implements Parent.GenServer.

Interacting with children inside the parent

From within the parent process, you can interact with the child processes using functions from the Parent module. All child processes should be started using Parent functions, such as Parent.start_child/2, because otherwise Parent won't be aware of these processes and won't be able to fulfill its guarantees.

Note that you can start children from any callback, not just during init/1. In addition, you don't need to start all children at once. Therefore, Parent.GenServer can prove useful when you need to make some runtime decisions:

  {:ok, child1} = Parent.start_child(child1_spec)

  if some_condition_met?,
    do: Parent.start_child(child2_spec)

  Parent.start_child(child3_spec)

However, bear in mind that this code won't be executed again if the processes are restarted.

Handling child termination

If a child process terminates and isn't restarted, the handle_stopped_children/2 callback is invoked. The default implementation does nothing.

The following example uses handle_stopped_children/2 to start a child task and report if it it crashes:

  defmodule MyJob do
    use Parent.GenServer, restart: :temporary

    def start_link(arg), do: Parent.GenServer.start_link(__MODULE__, arg)

    @impl GenServer
    def init(_) do
      {:ok, _} = Parent.start_child(%{
        id: :job,
        start: {Task, :start_link, [fn -> job(arg) end]},
        restart: :temporary,

        # handle_stopped_children won't be invoked without this
        ephemeral?: true
      })
      {:ok, nil}
    end

    @impl Parent.GenServer
    def handle_stopped_children(%{job: info}, state) do
      if info.reason != :normal do
        # report job failure
      end

      {:stop, reason, state}
    end
  end

handle_stopped_children can be useful to implement arbitrary custom behaviour, such as restarting after a delay, and using incremental backoff periods between two consecutive starts.

For example, this is how you could introduce a delay between two consecutive starts:

def handle_stopped_children(stopped_children, state) do
  Process.send_after(self, {:restart, stopped_children}, delay)
  {:noreply, state}
end

def handle_info({:restart, stopped_children}, state) do
  Parent.return_children(stopped_children)
  {:noreply, state}
end

Keep in mind that handle_stopped_children is only invoked if the child crashed on its own, and if it's not going to be restarted.

If the child was explicitly stopped via a Parent function, such as Parent.shutdown_child/1, this callback will not be invoked. The same holds for Parent.Client functions. If you want to unconditionally react to a termination of a child process, setup a monitor with Process.monitor and add a corresponding handle_info clause.

If the child was taken down because its lifecycle is bound to some other process, the corresponding handle_stopped_children won't be invoked. For example, if process A is bound to process B, and process B crashes, only one handle_stopped_children will be invoked (for the crash of process B). However, the corresponding info will contain the list of all associated siblings that have been taken down, and stopped_children will include information necessary to restart all of these siblings. Refer to Parent documentation for details on lifecycles binding.

Parent termination

The behaviour takes down the child processes before it terminates, to ensure that no child process is running after the parent has terminated. The children are terminated synchronously, one by one, in the reverse start order.

The termination of the children is done after the terminate/1 callback returns. Therefore in terminate/1 the child processes are still running, and you can interact with them, and even start additional children.

Caveats

Like any other Parent-based process, Parent.GenServer traps exits and uses the :infinity shutdown strategy. As a result, a parent process which blocks for a long time (e.g. because its communicating with a remote service) won't be able to handle child termination, and your fault-tolerance might be badly affected. In addition, a blocking parent might completely paralyze the system (or a subtree) shutdown. Setting a shutdown strategy to a finite time is a hacky workaround that will lead to lingering orphan processes, and might cause some strange race conditions which will be very hard to debug.

Therefore, be wary of having too much logic inside a parent process. Try to push as much responsibilities as possible to other processes, such as children or siblings, and use parent only for coordination and reporting tasks.

Finally, since parent trap exits, it's possible to receive an occasional stray :EXIT message if the child crashes during its initialization.

By default use Parent.GenServer receives such messages and ignores them. If you're implementing your own handle_info, make sure to include a clause for :EXIT messages:

  def handle_info({:EXIT, _pid, _reason}, state), do: {:noreply, state}