GenServer поведение

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

GenServer — это процесс, как и любой другой процесс Elixir, и он может использоваться для хранения состояния, выполнения кода асинхронно и так далее. Преимущество использования общего серверного процесса (GenServer), реализованного с помощью этого модуля, заключается в том, что у него будет стандартный набор функций интерфейса и функции отслеживания и обработки ошибок. Он также будет подходить для использования в дереве надзора.

Пример

Поведение GenServer абстрагирует общее взаимодействие клиент-сервер. Разработчикам требуется только реализовать вызовы и функциональность, которые их интересуют.

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

init/1 преобразует наш начальный аргумент в начальное состояние для GenServer. handle_call/3 срабатывает, когда сервер получает синхронное pop сообщение, извлекая элемент из стека и возвращая его пользователю. handle_cast/2 будет срабатывать, когда сервер получит асинхронное push сообщение, помещая элемент в стек:

defmodule Stack do
  use GenServer

  # Callbacks

  @impl true
  def init(elements) do
    initial_state = String.split(elements, ",", trim: true)
    {:ok, initial_state}
  end

  @impl true
  def handle_call(:pop, _from, state) do
    [to_caller | new_state] = state
    {:reply, to_caller, new_state}
  end

  @impl true
  def handle_cast({:push, element}, state) do
    new_state = [element | state]
    {:noreply, new_state}
  end
end

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

# Start the server
{:ok, pid} = GenServer.start_link(Stack, "hello,world")

# This is the client
GenServer.call(pid, :pop)
#=> "hello"

GenServer.cast(pid, {:push, "elixir"})
#=> :ok

GenServer.call(pid, :pop)
#=> "elixir"

Мы запускаем наш Stack, вызывая start_link/2, передавая модуль с реализацией сервера и его начальный аргумент со списком элементов через запятую. Поведение GenServer вызывает вызов init/1 для создания начального состояния GenServer. С этого момента GenServer имеет контроль, поэтому мы взаимодействуем с ним, отправляя два типа сообщений на клиенте. Сообщения call ожидают ответ от сервера (и поэтому являются синхронными), а сообщения cast — нет.

Каждый вызов GenServer.call/3 приводит к сообщению, которое должно быть обработано вызовом handle_call/3 в GenServer. Сообщение cast/2 должно быть обработано вызовом handle_cast/2. GenServer поддерживает 8 вызовов, но требуется только init/1.

use GenServer

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

Клиентский/серверный API

Хотя в примере выше мы использовали GenServer.start_link/3 и аналогичные функции для непосредственного запуска и общения с сервером, в большинстве случаев мы не вызываем функции GenServer напрямую. Вместо этого мы оборачиваем вызовы в новые функции, представляющие общедоступный API сервера. Эти тонкие оболочки называются клиентским API.

Вот лучшая реализация модуля Stack:

defmodule Stack do
  use GenServer

  # Client

  def start_link(default) when is_binary(default) do
    GenServer.start_link(__MODULE__, default)
  end

  def push(pid, element) do
    GenServer.cast(pid, {:push, element})
  end

  def pop(pid) do
    GenServer.call(pid, :pop)
  end

  # Server (callbacks)

  @impl true
  def init(elements) do
    initial_state = String.split(elements, ",", trim: true)
    {:ok, initial_state}
  end

  @impl true
  def handle_call(:pop, _from, state) do
    [to_caller | new_state] = state
    {:reply, to_caller, new_state}
  end

  @impl true
  def handle_cast({:push, element}, state) do
    new_state = [element | state]
    {:noreply, new_state}
  end
end

На практике часто используются как серверные, так и клиентские функции в одном модуле. Если реализация сервера и/или клиента становится сложной, вы можете поместить их в разные модули.

Как контролировать

GenServer чаще всего запускается в дереве надзора. При вызове use GenServer, он автоматически определяет функцию child_spec/1, которая позволяет запустить Stack напрямую под надзирателем. Чтобы запустить стандартный стек ["hello", "world"] под надзирателем, можно сделать следующее:

children = [
  {Stack, "hello,world"}
]

Supervisor.start_link(children, strategy: :one_for_all)

Обратите внимание, что указание модуля MyServer эквивалентно указанию кортежа {MyServer, []}.

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

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

Например:

use GenServer, restart: :transient, shutdown: 10_000

См. раздел «Спецификация дочернего элемента» в модуле Supervisor для получения более подробной информации. Аннотация @doc, непосредственно предшествующая use GenServer, будет прикреплена к сгенерированной функции child_spec/1.

При остановке GenServer, например, возвращая кортеж {:stop, reason, new_state} из вызова, причина завершения используется надзирателем для определения необходимости перезапуска GenServer. См. раздел «Причины завершения и перезапуск» в модуле Supervisor.

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

И start_link/3, и start/3 поддерживают GenServer для регистрации имени при запуске через параметр :name. Зарегистрированные имена также автоматически удаляются при завершении работы.

• атом — GenServer регистрируется локально (в текущем узле) с заданным именем с помощью Process.register/2.

• {:global, term} — GenServer регистрируется глобально с заданным значением с помощью функций модуля :global.

• {:via, module, term} — GenServer регистрируется с заданным механизмом и именем. Параметр :via ожидает модуль, который экспортирует register_name/2, unregister_name/1, whereis_name/1 и send/2. Одним из таких примеров является модуль :global, который использует эти функции для хранения списка имён процессов и соответствующих PID, доступных глобально для сети узлов Elixir. Elixir также поставляется с локальным, децентрализованным и масштабируемым реестром, называемым Registry, для локального хранения динамически генерируемых имён.

Например, мы могли бы запустить и зарегистрировать наш сервер Stack локально следующим образом:

# Start the server and register it locally with name MyStack
{:ok, _} = GenServer.start_link(Stack, "hello", name: MyStack)

# Now messages can be sent directly to MyStack
GenServer.call(MyStack, :pop)
#=> "hello"

После запуска сервера оставшиеся функции в этом модуле (call/3, cast/2 и другие) также будут принимать атом или любые {:global, ...} или {:via, ...} кортежи. В общем случае поддерживаются следующие форматы:

• PID
• атом, если сервер зарегистрирован локально
• {atom, node}, если сервер зарегистрирован локально на другом узле
• {:global, term}, если сервер глобально зарегистрирован
• {:via, module, name}, если сервер зарегистрирован через альтернативный реестр

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

Получение «обычных» сообщений

Цель GenServer — абстрагировать цикл «приём» для разработчиков, автоматически обрабатывая системные сообщения, поддерживая изменения кода, синхронные вызовы и многое другое. Поэтому никогда не следует вызывать собственный «приём» внутри вызовов GenServer, так как это приведёт к неправильной работе GenServer.

Помимо синхронного и асинхронного взаимодействия, предоставляемого call/3 и cast/2, «обычные» сообщения, отправленные функциями, такими как send/2, Process.send_after/4 и аналогичными, могут быть обработаны внутри вызова handle_info/2.

handle_info/2 может использоваться во многих ситуациях, таких как обработка сообщений DOWN, отправленных Process.monitor/1. Другой случай использования handle_info/2 — выполнение периодических задач с помощью Process.send_after/4:

defmodule MyApp.Periodically do
  use GenServer

  def start_link(_) do
    GenServer.start_link(__MODULE__, %{})
  end

  @impl true
  def init(state) do
    # Schedule work to be performed on start
    schedule_work()

    {:ok, state}
  end

  @impl true
  def handle_info(:work, state) do
    # Do the desired work here
    # ...

    # Reschedule once more
    schedule_work()

    {:noreply, state}
  end

  defp schedule_work do
    # We schedule the work to happen in 2 hours (written in milliseconds).
    # Alternatively, one might write :timer.hours(2)
    Process.send_after(self(), :work, 2 * 60 * 60 * 1000)
  end
end

Таймауты

Значение возвращаемого init/1 или любым из вызовов handle_* может включать значение таймаута в миллисекундах; если нет, предполагается :infinity. Таймаут может быть использован для обнаружения пауз в поступающих сообщениях.

Значение timeout() используется следующим образом:

• Если в процессе уже есть ожидающее сообщение, когда возвращается значение timeout(), таймаут игнорируется, и ожидающее сообщение обрабатывается как обычно. Это означает, что даже таймаут в 0 миллисекунд не гарантирует выполнения (если вы хотите выполнить другое действие немедленно и безусловно, используйте инструкцию :continue вместо этого).

• Если любое сообщение приходит до истечения заданного числа миллисекунд, таймаут очищается, и это сообщение обрабатывается как обычно.

• В противном случае, когда заданное число миллисекунд истекло без получения сообщения, вызывается handle_info/2 с :timeout в качестве первого аргумента.

Когда (не) следует использовать GenServer

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

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

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

def add(a, b) do
  GenServer.call(__MODULE__, {:add, a, b})
end

def subtract(a, b) do
  GenServer.call(__MODULE__, {:subtract, a, b})
end

def handle_call({:add, a, b}, _from, state) do
  {:reply, a + b, state}
end

def handle_call({:subtract, a, b}, _from, state) do
  {:reply, a - b, state}
end

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

def add(a, b) do
  a + b
end

def subtract(a, b) do
  a - b
end

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

Отладка с помощью модуля :sys

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

Давайте рассмотрим основные функции модуля :sys, используемые для отладки:

• :sys.get_state/2 — позволяет получить состояние процесса. В случае процесса GenServer это будет состояние модуля обратного вызова, как передаваемое в функции обратного вызова в качестве последнего аргумента.
• :sys.get_status/2 — позволяет получить статус процесса. Этот статус включает словарь процесса, запущен ли процесс или приостановлен, родительский PID, состояние отладчика и состояние модуля поведения, которое включает состояние модуля обратного вызова (как возвращается :sys.get_state/2). Можно изменить представление этого статуса, определив необязательный обратный вызов GenServer.format_status/2.
• :sys.trace/3 — выводит все системные события в :stdio.
• :sys.statistics/3 — управляет сбором статистики процесса.
• :sys.no_debug/2 — отключает все обработчики отладки для данного процесса. Очень важно отключить отладку, когда мы закончим. Чрезмерное количество обработчиков отладки или те, которые должны быть отключены, но не были, могут серьезно повредить производительность системы.
• :sys.suspend/2 — позволяет приостановить процесс, чтобы он отвечал только на системные сообщения, но не на другие. Приостановленный процесс можно активировать с помощью :sys.resume/2.

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

iex> {:ok, pid} = Stack.start_link([])
iex> :sys.statistics(pid, true) # turn on collecting process statistics
iex> :sys.trace(pid, true) # turn on event printing
iex> Stack.push(pid, 1)
*DBG* <0.122.0> got cast {push,1}
*DBG* <0.122.0> new state [1]
:ok

iex> :sys.get_state(pid)
[1]

iex> Stack.pop(pid)
*DBG* <0.122.0> got call pop from <0.80.0>
*DBG* <0.122.0> sent 1 to <0.80.0>, new state []
1

iex> :sys.statistics(pid, :get)
{:ok,
 [
   start_time: {{2016, 7, 16}, {12, 29, 41}},
   current_time: {{2016, 7, 16}, {12, 29, 50}},
   reductions: 117,
   messages_in: 2,
   messages_out: 0
 ]}

iex> :sys.no_debug(pid) # turn off all debug handlers
:ok

iex> :sys.get_status(pid)
{:status, #PID<0.122.0>, {:module, :gen_server},
 [
   [
     "$initial_call": {Stack, :init, 1},            # process dictionary
     "$ancestors": [#PID<0.80.0>, #PID<0.51.0>]
   ],
   :running,                                        # :running | :suspended
   #PID<0.80.0>,                                    # parent
   [],                                              # debugger state
   [
     header: 'Status for generic server <0.122.0>', # module status
     data: [
       {'Status', :running},
       {'Parent', #PID<0.80.0>},
       {'Logged events', []}
     ],
     data: [{'State', [1]}]
   ]
 ]}

Узнайте больше

Если вы хотите узнать больше о GenServer, руководство Elixir Getting Started предоставляет обучающий вводный курс. Документация и ссылки в Erlang также могут предоставить дополнительную информацию.

• GenServer — Руководство Elixir's Getting Started
• :gen_server документация модуля
• gen_server Поведение — Принципы проектирования OTP
• Клиенты и серверы — Learn You Some Erlang for Great Good!