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)andhandle_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:globalmodule.{:via, module, term}- the GenServer is registered with the given mechanism and name. The:viaoption 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
atomif 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.