Модуль поведения для реализации супервайзеров.

Супервайзер — это процесс, который контролирует другие процессы, которые мы называем дочерними процессами. Супервайзеры используются для построения иерархической структуры процессов, называемой деревом наблюдения. Деревья наблюдения обеспечивают отказоустойчивость и инкапсулируют, как запускаются и завершаются наши приложения.

Супервайзер можно запустить напрямую со списком спецификаций дочерних процессов с помощью start_link/2, или же вы можете определить супервайзер на основе модуля, реализующего необходимые обратные вызовы. В разделах ниже используется start_link/2 для запуска супервайзеров в большинстве примеров, но также есть отдельный раздел для супервайзеров на основе модулей.

Примеры

Для запуска супервайзера необходимо сначала определить дочерний процесс, который будет контролироваться. В качестве примера мы определим GenServer, универсальный сервер, который хранит счётчик. Другие процессы могут отправлять сообщения в этот процесс для чтения счётчика и увеличения его значения.

Примечание: на практике вы не определяли бы счётчик как GenServer. Вместо этого, если вам нужен счётчик, вы передадите его как входные и выходные данные в функции, которые его используют. Причина, по которой мы выбрали счётчик в этом примере, заключается в его простоте, так как это позволяет нам сосредоточиться на том, как работают супервайзеры.

defmodule Counter do
  use GenServer

  def start_link(arg) when is_integer(arg) do
    GenServer.start_link(__MODULE__, arg, name: __MODULE__)
  end

  ## Callbacks

  @impl true
  def init(counter) do
    {:ok, counter}
  end

  @impl true
  def handle_call(:get, _from, counter) do
    {:reply, counter, counter}
  end

  def handle_call({:bump, value}, _from, counter) do
    {:reply, counter, counter + value}
  end
end

Counter получает аргумент в start_link. Этот аргумент передаётся в обратный вызов init/1, который становится начальным значением счётчика. Наш счётчик обрабатывает две операции (известные как вызовы): :get, для получения текущего значения счётчика, и :bump, которая увеличивает счётчик на заданное value значение и возвращает старое значение счётчика.

Теперь мы можем запустить супервайзер, который запустит и будет контролировать наш процесс счётчика. Первый шаг — определить список спецификаций дочерних процессов, которые контролируют поведение каждого дочернего процесса. Каждая спецификация дочернего процесса представляет собой карту, как показано ниже:

children = [
  # The Counter is a child started via Counter.start_link(0)
  %{
    id: Counter,
    start: {Counter, :start_link, [0]}
  }
]

# Now we start the supervisor with the children and a strategy
{:ok, pid} = Supervisor.start_link(children, strategy: :one_for_one)

# After started, we can query the supervisor for information
Supervisor.count_children(pid)
#=> %{active: 1, specs: 1, supervisors: 0, workers: 1}

Обратите внимание, что при запуске GenServer мы регистрируем его с именем Counter через опцию name: __MODULE__. Это позволяет нам вызывать его напрямую и получить его значение:

GenServer.call(Counter, :get)
#=> 0

GenServer.cast(Counter, {:bump, 3})
#=> 0

GenServer.call(Counter, :get)
#=> 3

Однако в нашем сервере счётчика есть ошибка. Если мы вызовем :bump с нечисловым значением, он аварийно завершится:

GenServer.call(Counter, {:bump, "oops"})
** (exit) exited in: GenServer.call(Counter, {:bump, "oops"}, 5000)

К счастью, поскольку сервер контролируется супервайзером, супервайзер автоматически запустит новый, сбросив значение обратно к начальному значению 0:

GenServer.call(Counter, :get)
#=> 0

Супервайзеры поддерживают разные стратегии; в примере выше мы выбрали :one_for_one. Кроме того, каждый супервайзер может иметь множество рабочих процессов и/или других супервайзеров в качестве дочерних, и каждый из них имеет собственную конфигурацию (как указано в разделе "Спецификация дочернего процесса").

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

Спецификация дочернего процесса

Спецификация дочернего процесса описывает, как супервайзер запускает, завершает и перезапускает дочерние процессы.

Спецификация дочернего процесса — это карта, содержащая до 6 элементов. Первые два ключа в следующем списке являются обязательными, а остальные — необязательными:

• :id — любой термин, используемый для идентификации спецификации дочернего процесса внутри супервайзера; по умолчанию — указанный модуль. Этот ключ является обязательным. В случае конфликта значений :id, супервайзер откажется от инициализации и потребует явных идентификаторов. Однако это не относится к динамическим супервайзерам.

• :start — кортеж с модулем-функцией-аргументами, которые вызываются для запуска дочернего процесса. Этот ключ является обязательным.

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

• :shutdown — целое число или атом, определяющий, как дочерний процесс должен завершаться (см. раздел "Значения завершения" ниже). Этот ключ является необязательным и по умолчанию равен 5_000 если тип :worker, или :infinity если тип :supervisor.

• :type — указывает, что дочерний процесс является :worker или :supervisor . Этот ключ является необязательным и по умолчанию равен :worker.

• :modules — список модулей, используемых механизмами горячей замены кода для определения, какие процессы используют определённые модули. Обычно он устанавливается в модуль обратного вызова поведения, такого как GenServer, Supervisor, и т. п. Он устанавливается автоматически на основе значения :start и редко изменяется на практике.

Давайте разберёмся, за что отвечают опции :shutdown и :restart.

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

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

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

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

• :infinity — работает как целое число, за исключением того, что супервайзер будет неопределённо ждать завершения дочернего процесса. Если дочерний процесс является супервайзером, рекомендуемое значение — :infinity чтобы дать супервайзеру и его дочерним процессам достаточно времени для завершения. Эта опция может быть использована с обычными рабочими процессами, но это не рекомендуется и требует большой осторожности. Если не использовать её осторожно, дочерний процесс никогда не завершится, что помешает завершению вашего приложения.

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

Опция :restart управляет тем, что супервайзер должен считать успешным завершением, а что нет. Если завершение успешное, супервайзер не перезапускает дочерний процесс. Если дочерний процесс завершился аварийно, супервайзер запустит новый.

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

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

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

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

Для более полного понимания кодов завершения и их влияния, см. раздел "Причины завершения и перезапуска".

child_spec/1 функция

При запуске супервайзера мы можем передать список спецификаций дочерних процессов. Эти спецификации — карты, которые сообщают супервайзеру, как запустить, остановить и перезапустить каждый из его дочерних процессов:

%{
  id: Counter,
  start: {Counter, :start_link, [0]}
}

В представленной выше карте определён дочерний процесс с :id Counter, который запускается путём вызова Counter.start_link(0).

Однако определение спецификации дочернего процесса для каждого дочернего процесса в виде карты может быть достаточно подвержено ошибкам, так как мы можем изменить реализацию Counter и забыть обновить его спецификацию. Именно поэтому Elixir позволяет передавать кортеж с именем модуля и аргументом start_link вместо спецификации:

children = [
  {Counter, 0}
]

Супервайзер вызовет Counter.child_spec(0) для получения спецификации дочернего процесса. Теперь модуль Counter отвечает за создание собственной спецификации. Например, мы можем написать:

def child_spec(arg) do
  %{
    id: Counter,
    start: {Counter, :start_link, [arg]}
  }
end

К счастью для нас, use GenServer уже определяет Counter.child_spec/1 точно так же, как выше, поэтому вам не нужно писать определение самостоятельно. Если вы хотите настроить автоматически сгенерированную функцию child_spec/1, вы можете передать опции напрямую в use GenServer:

use GenServer, restart: :transient

Наконец, также возможно просто передать модуль Counter как дочерний процесс:

children = [
  Counter
]

При передаче только имени модуля это эквивалентно {Counter, []}, которое в нашем случае было бы неверным, поэтому мы всегда явно передаём начальный счётчик.

Заменив спецификацию дочернего процесса на {Counter, 0}, мы сохраняем её в инкапсулированном виде в модуле Counter . Теперь мы можем поделиться реализацией Counter с другими разработчиками, и они могут добавить её напрямую в своё дерево наблюдения, не беспокоясь о низкоуровневых деталях счётчика.

В целом, спецификация дочернего процесса может быть одной из следующих:

• карта, представляющая саму спецификацию дочернего процесса — как описано в разделе "Спецификация дочернего процесса"

• кортеж с модулем в качестве первого элемента и аргументом запуска во втором — например, {Counter, 0}. В этом случае вызывается Counter.child_spec(0), чтобы получить спецификацию дочернего процесса

• модуль — например, Counter. В этом случае вызывается Counter.child_spec([]), что неверно для счётчика, но полезно во многих других случаях, особенно когда вы хотите передать список опций дочернему процессу

Если вам нужно преобразовать кортеж {module, arg} или спецификацию дочернего процесса в виде модуля в спецификацию дочернего процесса или изменить саму спецификацию дочернего процесса, вы можете использовать функцию Supervisor.child_spec/2. Например, для запуска счётчика с другим :id и значением :shutdown в 10 секунд (10 000 миллисекунд):

children = [
  Supervisor.child_spec({Counter, 0}, id: MyCounter, shutdown: 10_000)
]

Стратегии и опции супервайзера

До сих пор мы запускали супервайзер, передавая единственный дочерний процесс в виде кортежа, а также стратегию, называемую :one_for_one:

children = [
  {Counter, 0}
]

Supervisor.start_link(children, strategy: :one_for_one)

Первый аргумент, переданный в start_link/2, — это список спецификаций дочерних процессов, как определено в разделе "child_spec/1" выше.

Второй аргумент — список опций в формате ключевое слово-значение:

• :strategy - параметр стратегии контроля. Может принимать значения :one_for_one, :rest_for_one или :one_for_all. Обязательно. См. раздел "Стратегии".

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

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

• :name - имя для регистрации процесса-контролёра. Поддерживаемые значения объяснены в разделе "Регистрация имён" в документации по GenServer. Необязательно.

Стратегии

Контролёры поддерживают различные стратегии контроля (через параметр :strategy, как показано выше):

• :one_for_one - если дочерний процесс завершается, перезапускается только этот процесс.

• :one_for_all - если дочерний процесс завершается, все остальные дочерние процессы завершаются, а затем все дочерние процессы (включая завершившийся) перезапускаются.

• :rest_for_one - если дочерний процесс завершается, завершается завершившийся дочерний процесс и все последующие запущенные дочерние процессы, после чего все они перезапускаются.

В приведенном выше контексте завершение процесса относится к неуспешному завершению, которое определяется параметром :restart.

Для эффективного контроля динамически созданных дочерних процессов см. DynamicSupervisor.

Регистрация имён

Контролёр подчиняется тем же правилам регистрации имен, что и GenServer. Подробнее об этих правилах можно узнать в документации по GenServer.

Модульно-базированные контролёры

В предыдущих примерах контролёр запускался путём передачи структуры контроля в start_link/2. Однако контролёры также можно создавать, явно определив модуль контроля:

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

  def start_link(init_arg) do
    Supervisor.start_link(__MODULE__, init_arg, name: __MODULE__)
  end

  @impl true
  def init(_init_arg) do
    children = [
      {Counter, 0}
    ]

    Supervisor.init(children, strategy: :one_for_one)
  end
end

Разница между этими подходами заключается в том, что модульно-базированный контролёр даёт вам больший контроль над инициализацией контролёра. Вместо вызова Supervisor.start_link/2 со списком спецификаций дочерних процессов, которые автоматически инициализируются, мы вручную инициализируем дочерние процессы, вызывая Supervisor.init/2 внутри его обратного вызова init/1. Supervisor.init/2 принимает те же параметры :strategy, :max_restarts, и :max_seconds что и start_link/2.

use Supervisor также определяет функцию child_spec/1, которая позволяет запускать MyApp.Supervisor в качестве дочернего процесса другого контролёра или в верхней части вашей иерархии контроля, как показано:

children = [
  MyApp.Supervisor
]

Supervisor.start_link(children, strategy: :one_for_one)

Общее руководство: используйте контролёр без модуля обратного вызова только в верхней части вашей иерархии контроля, обычно в обратном вызове Application.start/2. Рекомендуется использовать модульно-базированные контролёры для любого другого контролёра в вашем приложении, чтобы они могли работать как дочерние процессы другого контролёра в дереве. child_spec/1 генерируемый автоматически Supervisor, может быть настроен с помощью следующих параметров:

• :id - идентификатор спецификации дочернего процесса, по умолчанию текущий модуль
• :restart - время, когда контролёр должен быть перезапущен, по умолчанию :permanent

Аннотация @doc непосредственно перед use Supervisor будет прикреплена к сгенерированной функции child_spec/1.

Запуск и завершение

При запуске контролёр обходит все спецификации дочерних процессов, а затем запускает каждый дочерний процесс в порядке их определения. Это делается путём вызова функции, определённой в ключе :start в спецификации дочернего процесса, и по умолчанию соответствует start_link/1.

Затем для каждого дочернего процесса вызывается start_link/1 (или пользовательская). Функция start_link/1 должна возвращать {:ok, pid}, где pid - идентификатор процесса нового процесса, связанного с контролёром. Дочерний процесс обычно начинает свою работу, выполняя обратный вызов init/1. Как правило, обратный вызов init - место, где мы инициализируем и настраиваем дочерний процесс.

Процесс завершения происходит в обратном порядке.

При завершении работы контролёр завершает все дочерние процессы в обратном порядке их перечисления. Завершение происходит путём отправки сигнала завершения, через Process.exit(child_pid, :shutdown), дочернему процессу и последующего ожидания определённого интервала для завершения работы дочернего процесса. Этот интервал по умолчанию составляет 5000 миллисекунд. Если дочерний процесс не завершается в этот интервал, контролёр резко завершает его с причиной :kill.

Если дочерний процесс не обрабатывает сигналы завершения, он сразу же завершается при получении первого сигнала. Если дочерний процесс обрабатывает сигналы завершения, тогда вызывается обратный вызов terminate, и дочерний процесс должен завершиться в разумный промежуток времени до внезапного завершения контролёром.

Другими словами, если важно, чтобы процесс очистил за собой при завершении вашего приложения или дерева контроля, этот процесс должен обрабатывать сигналы завершения и его спецификация должна содержать корректное значение :shutdown, гарантируя, что он завершится в разумный промежуток времени.

Причины завершения и перезапуски

Контролёр перезапускает дочерний процесс в зависимости от его конфигурации :restart. Например, когда :restart установлено в значение :transient, контролёр не перезапускает дочерний процесс в случае его выхода с причиной :normal, :shutdown или {:shutdown, term}.

Возникает вопрос: какую причину завершения выбрать? Есть три варианта:

• :normal - в таких случаях выход не регистрируется, нет перезапуска в переходном режиме, и связанные процессы не выходят.

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

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

Обратите внимание, что контролёр, достигший максимальной интенсивности перезапусков, завершается с причиной :shutdown. В этом случае контролёр будет перезапущен только если в его спецификации дочернего процесса был задан параметр :restart со значением :permanent (по умолчанию).