Модуль поведения для реализации надсмотрщиков.

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

Надсмотрщик можно запустить напрямую со списком спецификаций дочерних процессов с помощью 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.call(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 и редко изменяется на практике.

• :significant — логическое значение, указывающее, должен ли дочерний процесс считаться важным с точки зрения автоматического завершения. Только :transient и :temporary дочерние процессы могут быть помечены как значимые. Этот ключ необязателен и по умолчанию равен false. Более подробные сведения см. в разделе «Автоматическое завершение» ниже.

Давайте разберемся, за что отвечают опции :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

Затем надсмотрщик вызовет Counter.start_link(arg) для запуска дочернего процесса. Этот поток показан на диаграмме ниже. Вызывающий процесс — это процесс, который запускает надсмотрщик. Надсмотрщик затем обращается к вашему коду (Модуль) для запуска дочернего процесса:

sequenceDiagram
    participant C as Caller (Process)
    participant S as Supervisor (Process)
    participant M as Module (Code)

    note right of C: child is a {module, arg} specification
    C->>+S: Supervisor.start_link([child])
    S-->>+M: module.child_spec(arg)
    M-->>-S: %{id: term, start: {module, :start_link, [arg]}}
    S-->>+M: module.start_link(arg)
    M->>M: Spawns child process (child_pid)
    M-->>-S: {:ok, child_pid} | :ignore | {:error, reason}
    S->>-C: {:ok, supervisor_pid} | {:error, reason}

К счастью для нас, 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.

• :auto_shutdown — опция автоматического завершения работы. Может быть :never, :any_significant, или :all_significant. Необязательно. См. раздел "Автоматическое завершение работы".

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

Стратегии

Надзорщики поддерживают различные стратегии надзора (через опцию :strategy, как показано выше):

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

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

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

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

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

Автоматическое завершение работы

Надзорщики способны автоматически завершать свою работу, когда дочерние процессы, помеченные как :significant, выходят из строя.

Надзорщики поддерживают различные опции автоматического завершения работы (через опцию :auto_shutdown, как показано выше):

• :never — это значение по умолчанию, автоматическое завершение работы отключено.

• :any_significant — если любой значимый дочерний процесс завершается, надзорщик автоматически завершит работу своих дочерних процессов, а затем и себя.

• :all_significant — когда все значимые дочерние процессы завершились, надзорщик автоматически завершит работу своих дочерних процессов, а затем и себя.

Только :transient и :temporary дочерние процессы могут быть помечены как значимые, и эта настройка влияет на поведение. Значимые :transient дочерние процессы должны завершаться нормально для того, чтобы автоматическое завершение работы считалось выполненным, где :temporary дочерние процессы могут завершаться по любой причине.

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

Надзорщик подчиняется тем же правилам регистрации имен, что и 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

При use Supervisor, модуль Supervisor установит @behaviour Supervisor и определит функцию child_spec/1, так что ваш модуль может использоваться как дочерний процесс в дереве надзора.

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}.

Эти выходы также влияют на журналирование. По умолчанию, такие поведения, как GenServers, не генерируют журналы ошибок, когда причина выхода — :normal, :shutdown или {:shutdown, term}.

Поэтому возникает вопрос: какую причину выхода следует выбрать? Существует три варианта:

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

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

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

В общем случае, если вы завершаетесь по ожидаемым причинам, вы хотите использовать :shutdown или {:shutdown, term}.

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