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

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

graph BT
    C(Client #3) ~~~ B(Client #2) ~~~ A(Client #1)
    A & B & C -->|request| GenServer
    GenServer -.->|reply| A & B & C

Пример

Поведение 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 вызывает ваш код (пунктирные линии):

sequenceDiagram
    participant C as Client (Process)
    participant S as Server (Process)
    participant M as Module (Code)

    note right of C: Typically started by a supervisor
    C->>+S: GenServer.start_link(module, arg, options)
    S-->>+M: init(arg)
    M-->>-S: {:ok, state} | :ignore | {:error, reason}
    S->>-C: {:ok, pid} | :ignore | {:error, reason}

    note right of C: call is synchronous
    C->>+S: GenServer.call(pid, message)
    S-->>+M: handle_call(message, from, state)
    M-->>-S: {:reply, reply, state} | {:stop, reason, reply, state}
    S->>-C: reply

    note right of C: cast is asynchronous
    C-)S: GenServer.cast(pid, message)
    S-->>+M: handle_cast(message, state)
    M-->>-S: {:noreply, state} | {:stop, reason, state}

    note right of C: send is asynchronous
    C-)S: Kernel.send(pid, message)
    S-->>+M: handle_info(message, state)
    M-->>-S: {:noreply, state} | {:stop, reason, state}

Как настроить управление

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 — абстрагировать цикл «receive» для разработчиков, автоматически обрабатывая системные сообщения, поддерживая изменения кода, синхронные вызовы и многое другое. Поэтому вы никогда не должны вызывать свой собственный «receive» внутри обратных вызовов 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/1.
• :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
• :gen_server документация модуля
• gen_server Behaviour - Принципы проектирования OTP
• Клиенты и серверы - Learn You Some Erlang for Great Good!