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

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

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

The 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 позволяет вам передать кортеж с именем модуля и аргументом запуска вместо спецификации:

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 (по умолчанию).