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

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

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

Примеры

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

defmodule Stack do
  use GenServer

  def start_link(state) do
    GenServer.start_link(__MODULE__, state, name: __MODULE__)
  end

  ## Callbacks

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

  @impl true
  def handle_call(:pop, _from, [head | tail]) do
    {:reply, head, tail}
  end

  @impl true
  def handle_cast({:push, head}, tail) do
    {:noreply, [head | tail]}
  end
end

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

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

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

# 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 мы регистрируем его с именем Stack, что позволяет нам напрямую вызывать его и получить то, что находится в стеке:

GenServer.call(Stack, :pop)
#=> :hello

GenServer.cast(Stack, {:push, :world})
#=> :ok

GenServer.call(Stack, :pop)
#=> :world

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

GenServer.call(Stack, :pop)
** (exit) exited in: GenServer.call(Stack, :pop, 5000)

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

GenServer.call(Stack, :pop)
#=> :hello

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

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

Спецификация дочерних элементов

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

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

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

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

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

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

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

Существует шестой ключ, :modules, который редко изменяется. Он устанавливается автоматически на основе значения в :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: Stack,
  start: {Stack, :start_link, [[:hello]]}
}

В приведённой выше карте определён начальник с :id Stack , запущенный вызовом Stack.start_link([:hello]).

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

children = [
  {Stack, [:hello]}
]

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

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

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

use GenServer, restart: :transient

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

children = [
  Stack
]

При передаче только имени модуля это эквивалентно {Stack, []}. Заменив карту спецификации на {Stack, [:hello]} или Stack, мы сохраняем спецификацию дочернего элемента, инкапсулированную в модуле Stack, используя реализацию по умолчанию, определённую в use GenServer. Теперь мы можем поделиться нашим рабочим процессом Stack с другими разработчиками, и они смогут напрямую добавить его в своё дерево управления, не беспокоясь о низкоуровневых деталях работы процесса.

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

• карта, представляющая саму спецификацию дочернего элемента — как описано в разделе "Спецификация дочернего элемента"
• кортеж с модулем в качестве первого элемента и аргументом запуска во втором — например, {Stack, [:hello]}. В этом случае вызывается Stack.child_spec([:hello]) для получения спецификации дочернего элемента
• модуль — например, Stack. В этом случае вызывается Stack.child_spec([]) для получения спецификации дочернего элемента

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

children = [
  Supervisor.child_spec({Stack, [:hello]}, id: MyStack, shutdown: 10_000)
]

Начальники на основе модулей

В примере выше начальник запускался путём передачи структуры управления в 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 = [
      {Stack, [:hello]}
    ]

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

Разница между этими двумя подходами заключается в том, что начальник на основе модуля даёт вам больший контроль над тем, как инициализируется начальник. Вместо вызова Supervisor.start_link/2 со списком детей, которые автоматически инициализируются, мы вручную инициализируем детей, вызвав Supervisor.init/2 внутри его обратного вызова init/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_link/2, init/2 и стратегии

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

children = [
  {Stack, [:hello]}
]

Supervisor.start_link(children, strategy: :one_for_one)

или изнутри обратного вызова init/1:

children = [
  {Stack, [:hello]}
]

Supervisor.init(children, strategy: :one_for_one)

Первый аргумент, переданный в start_link/2 и init/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.

Также существует устаревшая стратегия :simple_one_for_one, которая была заменена на DynamicSupervisor. Надзорщик :simple_one_for_one был похож на :one_for_one, но лучше подходит для динамического присоединения потомков. Многие функции в этом модуле вели себя немного по-другому, когда использовалась эта стратегия. Более подробная информация и стратегии миграции представлены в модуле DynamicSupervisor.

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

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

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

При запуске надзорщика он проходит по всем спецификациям потомков и затем запускает каждый потомок в порядке их определения. Это делается путем вызова функции, определенной под ключом :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 (значение по умолчанию).