Basic GenServer Implementation

Welcome to your first hands-on GenServer lesson in this course on OTP Fundamentals. We will build a simple Stack server that holds state, accepts updates, and responds to requests using standard GenServer patterns. You will see how to start a GenServer, initialize state, expose a small public API, and handle synchronous vs. asynchronous messages. GenServer is part of Elixir/OTP, so there is nothing extra to install.

Here is how we define the module, start the process, and set the initial state:

defmodule Stack do
  use GenServer

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

  def init(initial_stack) do
    {:ok, initial_stack}
  end

Explanation:

• use GenServer brings in the GenServer behavior.
• start_link/1 boots the server and registers it under the module name (name: __MODULE__), so you do not need to pass a PID later.
• init/1 sets the initial state to the provided list.

We provide a clean API that hides GenServer details from callers:

  def push(item) do
    GenServer.cast(__MODULE__, {:push, item})
  end

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

Explanation:

• push/1 uses GenServer.cast/2, which is asynchronous (fire-and-forget). It returns immediately.
• pop/0 uses GenServer.call/2, which is synchronous. It waits for a reply from the server.
• Both target the registered name (__MODULE__), not a PID.

Note: GenServer.call/2 has a default timeout of 5000 milliseconds (5 seconds). If the server does not reply within this time, a GenServer.CallError (timeout) is raised. You can override the timeout by calling GenServer.call(__MODULE__, :pop, 10_000) for a 10-second timeout. In production code, you should consider handling possible timeout errors using try/rescue or by setting an appropriate timeout for your use case.

These callbacks update and read the server’s state:

  def handle_cast({:push, item}, stack) do
    {:noreply, [item | stack]}
  end

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

  def handle_call(:pop, _from, []) do
    {:reply, nil, []}
  end
end

Explanation:

• handle_cast/2 processes the async push by prepending the item to the list. It returns {:noreply, new_state}.
• handle_call/3 for :pop matches two cases:
  • Non-empty stack [head | tail]: replies with head and keeps tail as the new state.
  • Empty stack []: replies with nil and keeps the state unchanged.

{:ok, _pid} = Stack.start_link([])
Stack.push(1)
Stack.push(2)
Stack.push(3)
Process.sleep(50) # Ensure async casts are processed before popping
IO.puts(Stack.pop())
IO.puts(Stack.pop())
Process.sleep(100) # Ensure all async casts are processed before script exits

Explanation:

• We start with an empty stack, push 1, 2, and 3, then pause briefly with Process.sleep/50 to allow the asynchronous cast operations to complete before popping.
• This ensures that the pop calls reflect the expected stack state and you see 3 and then 2 printed.
• The final Process.sleep/100 gives time for any remaining async casts to be handled before the script exits.

You now have a working mental model for GenServer: booting and initialization for setup, asynchronous updates for fire-and-forget tasks, synchronous requests for retrieving data, and callbacks for managing state. When you are ready, head to the practice section and apply what you have learned to reinforce these patterns.