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

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

Пример

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

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

defmodule Stack do
  use GenServer

  # 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, element}, state) do
    {:noreply, [element | state]}
  end
end

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

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

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

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

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

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

Клиент/Сервер API

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

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

defmodule Stack do
  use GenServer

  # Client

  def start_link(default) when is_list(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(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, element}, state) do
    {:noreply, [element | state]}
  end
end

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

Как настроить надзор

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

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

Supervisor.start_link(children, strategy: :one_for_all)

Обратите внимание, что вы также можете запустить его просто как Stack, что эквивалентно {Stack, []}.

children = [
  Stack # The same as {Stack, []}
]

Supervisor.start_link(children, strategy: :one_for_all)

В обоих случаях Stack.start_link/1 всегда вызывается.

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

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

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

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