用於實作客戶端伺服器關係伺服器的行為模組。

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 行為，只專注於堆疊實作。我們現在可以使用 GenServer API 透過建立一個程序並傳送訊息給它，來與服務互動。

# 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"

我們呼叫 start_link/2 來啟動我們的 Stack，傳遞包含伺服器實作的模組，以及其初始引數（元素清單，以逗號分隔）。GenServer 行為呼叫 init/1 回呼，以建立初始的 GenServer 狀態。從此點開始，GenServer 已取得控制權，因此我們透過在客戶端傳送兩種訊息來與之互動。呼叫訊息預期伺服器會回覆（因此是同步的），而傳送訊息則不會。

每次呼叫 GenServer.call/3 都會產生一則訊息，必須由 GenServer 中的 handle_call/3 回呼處理。cast/2 訊息必須由 handle_cast/2 處理。GenServer 支援 8 個回呼，但僅 init/1 是必要的。

使用 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 模組中的「子項規格」區段，以取得更詳細的資訊。緊接在 use GenServer 之前的 @doc 註解會附加到產生的 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，這些名稱和 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 可用於許多情況，例如處理 Process.monitor/1 傳送的監視器 DOWN 訊息。另一個 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 指令）。

• 如果在指定的毫秒數到期前有任何訊息到達，則會清除逾時，並照常處理該訊息。

• 否則，在指定的毫秒數到期且沒有訊息到達時，會以 :timeout 作為第一個引數呼叫 handle_info/2。

何時（不）使用 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 模組進行除錯

GenServers，作為 特殊程序，可以使用 :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 入門指南提供了類似教學課程的簡介。Erlang 中的文件和連結也可以提供額外的見解。

• GenServer - Elixir 入門指南
• :gen_server 模組文件
• gen_server 行為 - OTP 設計原則
• 客戶端和伺服器 - 學習一些 Erlang，大有益處！