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], где модуль — имя модуля коллбэка только в том случае, если процесс дочернего элемента является 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 - если процесс дочернего элемента является супервайзером, это механизм, позволяющий поддереву достаточно времени для завершения; его также можно использовать с рабочими элементами с осторожностью

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

Резюме

Типы

child_id()

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

modules()

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

restart()

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

shutdown()

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

spec()

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

strategy()

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

worker()

Поддерживаемые значения рабочих элементов

Функции

supervise(children, options)

Получает список 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() :: 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()}

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

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