Supervisor.Spec

Функции для определения спецификаций супервайзора.

Пример

Используя функции в этом модуле, можно указать дочерние элементы, которые должны использоваться под супервайзором, начиная с Supervisor.start_link/2:

import Supervisor.Spec

children = [
  worker(MyWorker, [arg1, arg2, arg3]),
  supervisor(MySupervisor, [arg1])
]

Supervisor.start_link(children, strategy: :one_for_one)

Иногда удобно определять супервайзоров, поддерживаемых модулем:

defmodule MySupervisor do
  use Supervisor

  def start_link(arg) do
    Supervisor.start_link(__MODULE__, arg)
  end

  def init(arg) do
    children = [
      worker(MyWorker, [arg], restart: :temporary)
    ]

    supervise(children, strategy: :simple_one_for_one)
  end
end

Обратите внимание, что в этом случае нам не нужно явно импортировать Supervisor.Spec, так как use Supervisor автоматически это делает. Определение супервайзора на основе модуля может быть полезно, например, для выполнения задач инициализации в c:init/1 обратном вызове.

Параметры супервайзора и рабочего процесса

В примере выше мы определили спецификации для рабочих процессов и супервайзоров. Эти спецификации (как для рабочих процессов, так и для супервайзоров) принимают следующие параметры:

• :id - имя, используемое для идентификации спецификации дочернего элемента внутри супервайзора; по умолчанию соответствует имени модуля для дочернего рабочего процесса/супервайзора

• :function - функция, которая вызывается для запуска дочернего элемента

• :restart - атом, определяющий, когда завершившийся дочерний процесс должен быть перезапущен (см. раздел «Значения перезапуска» ниже)

• :shutdown - атом, определяющий, как должен быть завершен дочерний процесс (см. раздел «Значения завершения» ниже)

• :modules - должен быть списком с одним элементом [module], где module — имя модуля обратного вызова только в том случае, если дочерний процесс является Supervisor или GenServer; если дочерний процесс является GenEvent, то :modules должен быть :dynamic

Значения перезапуска (:restart)

Следующие значения перезапуска поддерживаются в параметре :restart:

• :permanent - дочерний процесс всегда перезапускается

• :temporary - дочерний процесс никогда не перезапускается (даже когда стратегия супервайзора — :rest_for_one или :one_for_all)

• :transient - дочерний процесс перезапускается только в случае ненормального завершения, т. е. с причиной выхода, отличной от :normal, :shutdown или {:shutdown, term}

Значения завершения (:shutdown)

Следующие значения завершения поддерживаются в параметре :shutdown:

• :brutal_kill - дочерний процесс безусловно завершается с помощью Process.exit(child, :kill)

• :infinity - если дочерний процесс является супервайзором, это механизм для предоставления поддереву достаточного времени для завершения; его также можно использовать с рабочими процессами с осторожностью

• любое целое число — значение :shutdown также может быть любым целым числом, означающим, что супервайзор говорит дочернему процессу завершиться, вызвав Process.exit(child, :shutdown), а затем ожидает сигнал выхода обратно. Если сигнал выхода не получен в течение указанного времени (значение этого параметра в миллисекундах), дочерний процесс безусловно завершается с помощью Process.exit(child, :kill)

Краткое описание

Типы

child_id()

Поддерживаемые значения идентификаторов

modules()

Поддерживаемые значения модулей

restart()

Поддерживаемые значения перезапуска

shutdown()

Поддерживаемые значения завершения

spec()

Спецификация супервайзора

strategy()

Поддерживаемые стратегии

worker()

Поддерживаемые значения рабочих процессов

Функции

supervise(children, options)

Получает список дочерних элементов (рабочих процессов или супервайзоров) для контроля и набор параметров

supervisor(module, args, options \\ [])

Определяет указанный module как супервайзор, который будет запущен с заданными аргументами

worker(module, args, options \\ [])

Определяет указанный module как рабочий процесс, который будет запущен с заданными аргументами

Типы

child_id()

child_id() :: term()

Поддерживаемые значения идентификаторов

modules()

modules() :: :dynamic | [module()]

Поддерживаемые значения модулей

restart()

restart() :: :permanent | :transient | :temporary

Поддерживаемые значения перезапуска

shutdown()

shutdown() :: :brutal_kill | :infinity | non_neg_integer()

Поддерживаемые значения завершения

spec()

spec() :: {child_id(), start_fun :: {module(), atom(), [term()]}, restart(), shutdown(), worker(), modules()}

Спецификация супервайзора

strategy()

strategy() ::
  :simple_one_for_one |
  :one_for_one |
  :one_for_all |
  :rest_for_one

Поддерживаемые стратегии

worker()

worker() :: :worker | :supervisor

Поддерживаемые значения рабочих процессов

Функции

supervise(children, options)

supervise([spec()], [strategy: strategy(), max_restarts: non_neg_integer(), max_seconds: non_neg_integer()]) :: {:ok, tuple()}

Получает список дочерних элементов (рабочих процессов или супервайзоров) для контроля и набор параметров.

Возвращает кортеж, содержащий спецификацию супервайзора. Этот кортеж может использоваться в качестве значения возврата c:init/1 обратного вызова при реализации модульного супервайзора.

Примеры

supervise(children, strategy: :one_for_one)

Параметры

• :strategy - параметр стратегии перезапуска. Может быть :one_for_one, :rest_for_one, :one_for_all, или :simple_one_for_one. Дополнительную информацию о стратегиях можно найти в документации модуля Supervisor.

• :max_restarts - максимальное количество перезапусков, разрешенных в течение определенного временного интервала. По умолчанию 3.

• :max_seconds - временной интервал, в течение которого применяется :max_restarts. По умолчанию 5.

Параметр :strategy является обязательным и по умолчанию разрешает максимум 3 перезапуска в течение 5 секунд. Для подробного описания доступных стратегий обратитесь к модулю Supervisor.

supervisor(module, args, options \\ [])

supervisor(module(), [term()], [restart: restart(), shutdown: shutdown(), id: term(), function: atom(), modules: modules()]) :: spec()

Определяет указанный module как супервайзор, который будет запущен с заданными аргументами.

supervisor(ExUnit.Runner, [], restart: :permanent)

По умолчанию вызывается функция start_link для данного модуля. В целом, значения параметров по умолчанию:

[id: module,
 function: :start_link,
 restart: :permanent,
 shutdown: :infinity,
 modules: [module]]

Дополнительную информацию о параметрах см. в документации модуля Supervisor.Spec.

worker(module, args, options \\ [])

worker(module(), [term()], [restart: restart(), shutdown: shutdown(), id: term(), function: atom(), modules: modules()]) :: spec()

Определяет указанный module как рабочий процесс, который будет запущен с заданными аргументами.

worker(ExUnit.Runner, [], restart: :permanent)

По умолчанию вызывается функция start_link для данного модуля. В целом, значения параметров по умолчанию:

[id: module,
 function: :start_link,
 restart: :permanent,
 shutdown: 5000,
 modules: [module]]

Дополнительную информацию о параметрах см. в документации модуля Supervisor.Spec.