Supervisor.Spec

ПРИМЕЧАНИЕ: Функции в этом модуле устарели и не работают с основанными на модуле дочерними спецификациями, представленными в Elixir v1.5. Обратитесь к документации Supervisor вместо этого.

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

Пример

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

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

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

• :brutal_kill - дочерний процесс безусловно завершается с помощью Process.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() :: timeout() | :brutal_kill

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

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: pos_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.