A behaviour module for implementing the server of a client-server relation.

A GenServer is a process as any other Elixir process and it can be used to keep state, execute code asynchronously and so on. The advantage of using a generic server process (GenServer) implemented using this module is that it will have a standard set of interface functions and include functionality for tracing and error reporting. It will also fit into a supervision tree.

Example

The GenServer behaviour abstracts the common client-server interaction. Developers are only required to implement the callbacks and functionality they are interested in.

Let’s start with a code example and then explore the available callbacks. Imagine we want a GenServer that works like a stack, allowing us to push and pop items:

defmodule Stack do
  use GenServer

  # Callbacks

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

  def handle_cast({:push, item}, state) do
    {:noreply, [item|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

We start our Stack by calling start_link/3, passing the module with the server implementation and its initial argument (a list representing the stack containing the item :hello). We can primarily interact with the server by sending two types of messages. call messages expect a reply from the server (and are therefore synchronous) while cast messages do not.

Every time you do a GenServer.call/3, the client will send a message that must be handled by the handle_call/3 callback in the GenServer. A cast/2 message must be handled by handle_cast/2.

Callbacks

There are 6 callbacks required to be implemented in a GenServer. By adding use GenServer to your module, Elixir will automatically define all 6 callbacks for you, leaving it up to you to implement the ones you want to customize. The callbacks are:

• init(args) - invoked when the server is started.

  It must return:

  • {:ok, state}
  • {:ok, state, timeout}
  • :ignore
  • {:stop, reason}

• handle_call(msg, {from, ref}, state) and handle_cast(msg, state) - invoked to handle call (sync) and cast (async) messages.

  It must return:

  • {:reply, reply, new_state}
  • {:reply, reply, new_state, timeout}
  • {:reply, reply, new_state, :hibernate}
  • {:noreply, new_state}
  • {:noreply, new_state, timeout}
  • {:noreply, new_state, :hibernate}
  • {:stop, reason, new_state}
  • {:stop, reason, reply, new_state}

• handle_info(msg, state) - invoked to handle all other messages which are received by the process.

  It must return:

  • {:noreply, state}
  • {:noreply, state, timeout}
  • {:stop, reason, state}

• terminate(reason, state) - called when the server is about to terminate, useful for cleaning up. It must return :ok.

• code_change(old_vsn, state, extra) - called when the application code is being upgraded live (hot code swapping).

  It must return:

  • {:ok, new_state}
  • {:error, reason}

Name Registration

Both start_link/3 and start/3 support the GenServer to register a name on start via the :name option. Registered names are also automatically cleaned up on termination. The supported values are:

• an atom - the GenServer is registered locally with the given name using Process.register/2.

• {:global, term}- the GenServer is registered globally with the given term using the functions in the :global module.

• {:via, module, term} - the GenServer is registered with the given mechanism and name. The :via option expects a module name to control the registration mechanism alongside a name which can be any term.

For example, we could start and register our Stack server locally as follows:

# 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

Once the server is started, the remaining functions in this module (call/3, cast/2, and friends) will also accept an atom, or any :global or :via tuples. In general, the following formats are supported:

• a pid
• an atom if the server is locally registered
• {atom, node} if the server is locally registered at another node
• {:global, term} if the server is globally registered
• {:via, module, name} if the server is registered through an alternative registry

Client / Server APIs

Although in the example above we have used GenServer.start_link/3 and friends to directly start and communicate with the server, most of the time we don’t call the GenServer functions directly. Instead, we wrap the calls in new functions representing the public API of the server.

Here is a better implementation of our Stack module:

defmodule Stack do
  use GenServer

  # Client

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

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

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

  # Server (callbacks)

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

  def handle_call(request, from, state) do
    # Call the default implementation from GenServer
    super(request, from, state)
  end

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

  def handle_cast(request, state) do
    super(request, state)
  end
end

In practice, it is common to have both server and client functions in the same module. If the server and/or client implementations are growing complex, you may want to have them in different modules.

Learn more

If you wish to find out more about gen servers, Elixir getting started guides provide a tutorial-like introduction. The documentation and links in Erlang can also provide extra insight.

• http://elixir-lang.org/getting_started/mix/1.html
• http://www.erlang.org/doc/man/gen_server.html
• http://www.erlang.org/doc/design_principles/gen_server_concepts.html
• http://learnyousomeerlang.com/clients-and-servers