Supervisorповедение

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

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

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

К счастью для нас, 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 (по умолчанию).