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 автоматически делает это. Определение супервайзора на основе модуля может быть полезно, например, для выполнения задач инициализации в init/1 обратном вызове.

Параметры супервайзора и работника

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

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

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

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

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

• :modules — должен быть списком с одним элементом [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 — дочерний процесс безусловно завершается с помощью exit(child, :kill)

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

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

Сводка

Типы

child_id()

Поддерживаемые значения 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

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

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}

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

Возвращает кортеж, содержащий спецификацию супервайзора. Этот кортеж может быть использован в качестве значения возврата 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.