Erlang GenServer Explained: From start_link/4 to Callbacks, State, and Supervision

1. Introduction: What Problem Does GenServer Solve?

Imagine you are building a real-time multiplayer game or a simple counter service in Erlang. You know that Erlang is famous for lightweight concurrency. To create a process that stays alive and continuously receives messages, you might write code like this using spawn/1:

spawn(fun loop/0).

loop() ->
    receive
        Message ->
            io:format("Received: ~p~n", [Message]),
            loop()
    end.

Let's analyze what is happening here:

The process: spawn/1 creates a new concurrent background Erlang process.
The receive loop: The loop/0 function sits inside a continuous tail-recursive call. It pauses execution at receive until a message arrives in its mailbox, prints it, and calls loop() again to keep waiting.

Now think about building a production application. What if you need to hold state? What if you need synchronous call-and-response behavior? What if the code crashes or needs hot upgrades? You would have to manually write standard loops, message matching, error handling, state passing, and response mechanisms for every single process in your codebase.

Yeh repetitive logic baar-baar likhna padega! Writing custom receive loops over and over is error-prone, hard to read, and difficult to maintain across teams.

The Solution: OTP provides behaviours like gen_server. GenServer abstracts away the infinite recursive loop, message extraction, mailbox checks, and state maintenance. It gives you a standardized, rock-solid template to build long-running server processes.

2. First Understand: What is an Erlang Process?

Before jumping into GenServer internals, let's review basic Erlang concurrency mechanics:

Process: An isolated unit of execution inside the BEAM virtual machine (not an OS process). Erlang can handle millions of them simultaneously because they take up tiny amounts of memory (~a few KB).
Message Passing: Erlang processes share no memory. They communicate exclusively by sending immutable messages to each other.
PID (Process Identifier): Every process gets a unique address called a PID. You use this address to send messages to that specific process.

Pid = spawn(fun() ->
    receive
        Message ->
            io:format("Received: ~p~n", [Message])
    end
end).

Pid ! hello.

Process A Process B (PID) | | | -------- Send message 'hello' -----> | [ Mailbox ] | ( Pid ! hello ) | | | | v v | Print "Received: hello"

A GenServer is simply an Erlang process running under the hood, but wrapped with structured OTP patterns so you don't have to manually manage its mailbox or PID logic.

3. What is OTP?

Beginners often get confused by the term OTP (Open Telecom Platform). OTP is not just an external library—it is the standard architecture built right into Erlang. It offers reusable behaviours and battle-tested design patterns to build fault-tolerant, scalable applications effortlessly.

OTP Framework | +-- gen_server (Generic State & Message Manager) +-- supervisor (Process Monitor & Crash Recovery) +-- application (Packaged Executable Unit) +-- gen_statem (State Machine Behaviour) +-- gen_event (Event Handling Behaviour)

Think of OTP as a framework where gen_server manages process logic, and supervisor watches those processes to restart them if they crash.

4. What is GenServer?

Definition: A GenServer (Generic Server) is an OTP behaviour that provides a standardized framework to build a long-running Erlang process that maintains internal state and handles incoming requests.

Let's break down its three core pillars:

Long-running process: It starts up and stays active in memory waiting for messages.
State: It holds variables (integers, maps, records) across requests.
Message handling: It cleanly separates messages into synchronous calls (needs a reply) and asynchronous casts (fire-and-forget).

Real-world Analogy: Think of a GenServer as an employee sitting at a desk desk in a office. The employee holds a register notebook (State). Clients walk up with requests (Messages). The employee processes the work, updates the notebook state, responds to the client if needed, and waits for the next request.

5. Create the Smallest Possible GenServer

Here is a complete, minimal, valid GenServer module named counter:

-module(counter).

-behaviour(gen_server).

-export([start_link/0]).

-export([
    init/1,
    handle_call/3,
    handle_cast/2,
    handle_info/2,
    terminate/2,
    code_change/3
]).

start_link() ->
    gen_server:start_link(
        {local, ?MODULE},
        ?MODULE,
        [],
        []
    ).

init([]) ->
    {ok, 0}.

Line-by-Line Breakdown:

-module(counter). defines our module name.
-behaviour(gen_server). tells Erlang: "This module implements the GenServer behavior. Check that I provided all required callbacks!"
-export([...]). exports our custom functions and the standard callback functions so OTP can call them.
start_link/0 is our helper function to kick off the server process.
init([]) -> {ok, 0}. sets up the initial process state (in this case, the integer 0).

6. Deeply Explain gen_server:start_link/4

The gen_server:start_link/4 call is where the magic begins. Let's break down its four parameters:

gen_server:start_link(
    ServerName,
    Module,
    Args,
    Options
)

Parameter 1: ServerName (`{local, ?MODULE}`)

Normally, processes are identified by PIDs like <0.154.0>. But passing PIDs around everywhere is messy. Process Registration lets you register a process under a global or local name atom.

local means registered only on the current BEAM node.
?MODULE is a macro expanding to the module name (counter).
So, {local, ?MODULE} registers this process under the local alias name counter.

Parameter 2: Module (`?MODULE`)

This tells OTP which module contains the callback functions (e.g., init/1, handle_call/3). Here, ?MODULE tells it: "Look right inside this current file for callbacks."

Parameter 3: Args (`[]`)

Parameters passed straight into our init/1 callback function. For example:

start_link(InitialValue) ->
    gen_server:start_link(
        {local, ?MODULE},
        ?MODULE,
        [InitialValue],
        []
    ).

init([InitialValue]) ->
    {ok, InitialValue}.

Parameter 4: Options (`[]`)

Options for debugging, tracing, or memory management. Beginners can safely pass an empty list [].

7. Explain Why It Is Called start_link

Why do we use start_link instead of just start?

In Erlang, a Link creates a bi-directional link between two processes. If process A is linked to process B, and process B crashes, process A receives a signal notification (or crashes too, depending on setup).

Supervisor Process | | ( linked via start_link/4 ) v GenServer Process (child)

Supervisors use this link to catch crashes and immediately restart failing GenServers. Thus, standard OTP applications almost exclusively use start_link.

8. Explain GenServer State

How does state work in a language with immutable variables?

When init/1 executes, it returns {ok, State}. GenServer holds onto that State term in memory. Every time a callback function is triggered, OTP passes the current State in, receives the updated NewState back, and uses NewState for the next message execution!

Initial State (0) | increment message | v State (1) | increment message | v State (2)

9. Explain handle_call/3

handle_call/3 handles Synchronous messages. Use this when the caller process needs a direct response back (request-response model).

% API Function (Called by Client)
get() ->
    gen_server:call(?MODULE, get).

% Callback (Executed inside GenServer process)
handle_call(get, _From, State) ->
    {reply, State, State}.

Flow:

Caller Process GenServer Process | | | --- gen_server:call(counter, get) ------> | (triggers handle_call) | (Caller pauses & waits) | returns {reply, State, State} | <------------ Reply (State) ------------- | v v (Resumes execution) (Waits for next request)

gen_server:call/2 sends a request and blocks the caller process until a reply arrives.
_From holds the PID of the caller process.
{reply, ReplyValue, NewState} tells OTP to return ReplyValue to the client and store NewState.

10. Explain handle_cast/2

handle_cast/2 handles Asynchronous messages. Use this for fire-and-forget commands where the caller doesn't need to wait for a response.

% API Function
increment() ->
    gen_server:cast(?MODULE, increment).

% Callback
handle_cast(increment, State) ->
    {noreply, State + 1}.

Comparison:

call: Synchronous (Request + Wait for Response)
cast: Asynchronous (Send Message + Keep Running Immediately)

11. Explain handle_info/2

What if someone sends a raw message using the bang operator (Pid ! hello) or a timer expires? These messages bypass call and cast.

handle_info/2 is the fallback callback for raw Erlang messages, timers, and node signals.

% In REPL or another process:
counter ! hello

% Inside counter.erl:
handle_info(hello, State) ->
    io:format("Received out-of-band hello!~n"),
    {noreply, State}.

12. Build the Complete Counter GenServer

Here is the entire working code combining everything we've learned into a single file:

-module(counter).

-behaviour(gen_server).

%% Client API
-export([start_link/0, get/0, increment/0]).

%% gen_server callbacks
-export([
    init/1,
    handle_call/3,
    handle_cast/2,
    handle_info/2,
    terminate/2,
    code_change/3
]).

%%% Client API %%%

start_link() ->
    gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).

get() ->
    gen_server:call(?MODULE, get).

increment() ->
    gen_server:cast(?MODULE, increment).

%%% Callback Implementations %%%

init([]) ->
    {ok, 0}.

handle_call(get, _From, State) ->
    {reply, State, State}.

handle_cast(increment, State) ->
    {noreply, State + 1}.

handle_info(hello, State) ->
    io:format("Received raw hello message!~n"),
    {noreply, State};
handle_info(_Info, State) ->
    {noreply, State}.

terminate(_Reason, _State) ->
    ok.

code_change(_OldVsn, State, _Extra) ->
    {ok, State}.

How to test it in the Erlang Shell (erl):

1> c(counter).
{ok,counter}
2> counter:start_link().
{ok,<0.152.0>}
3> counter:get().
0
4> counter:increment().
ok
5> counter:get().
1
6> counter:increment().
ok
7> counter:get().
2

13. Explain the Complete Message Flow

=== CAST (Async Flow) === Client Calls counter:increment() | v gen_server:cast({local, counter}, increment) | v Placed in GenServer Mailbox | v GenServer extracts message -> invokes handle_cast(increment, State) | v Returns {noreply, State + 1} | v GenServer updates internal state and waits for next message === CALL (Sync Flow) === Client Calls counter:get() | v gen_server:call({local, counter}, get) | v Placed in GenServer Mailbox (Client Process Blocks) | v GenServer extracts message -> invokes handle_call(get, From, State) | v Returns {reply, CurrentState, CurrentState} | v OTP sends CurrentState back to Client -> Client Unblocks & Returns Value

14. Explain the Important Callbacks

Callback	Purpose
`init/1`	Initializes the process state on start.
`handle_call/3`	Handles synchronous requests (returns a reply).
`handle_cast/2`	Handles asynchronous requests (no reply).
`handle_info/2`	Handles raw messages, timers, and exit signals.
`terminate/2`	Cleanup hook executed when process terminates.
`code_change/3`	Handles hot code upgrades during runtime.

Common Callback Return Values:

{ok, State}: Successfully initialized state.
{reply, Reply, NewState}: Send Reply to caller and set state to NewState.
{noreply, NewState}: Don't reply to anyone, set state to NewState.
{stop, Reason, Reply, NewState}: Reply, then shut down the server process with Reason.

15. GenServer vs Raw Spawn/Receive

Raw Process Architecture: spawn -> receive loop -> pattern match -> manual state passing -> manual crash handling GenServer Architecture: start_link -> OTP Engine -> Callbacks (init/call/cast) -> Standardized Supervision & Upgrades

Raw processes are great for lightweight disposable tasks. GenServers are the standard for long-lived, maintainable production infrastructure.

16. Explain Supervision

Once you understand GenServers, supervision becomes trivial. A Supervisor is an OTP process whose sole job is to manage the lifecycle of child processes (like GenServers).

Root Application | Supervisor Process | +----> Counter GenServer (start_link) | +----> Kafka Config Worker (start_link) | +----> Database Worker (start_link)

Because your GenServer registered using start_link, if a bug causes the GenServer to crash, the Supervisor detects the termination and instantly starts a fresh copy of the GenServer!

17. Real-World Example: Kafka Configuration Worker

Let's look at a practical usage beyond counters: a process holding application configuration for a messaging broker.

-module(kafka_config).

-behaviour(gen_server).

-export([start_link/0, get_config/0, update_topic/1]).
-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2, code_change/3]).

start_link() ->
    gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).

get_config() ->
    gen_server:call(?MODULE, get_config).

update_topic(NewTopic) ->
    gen_server:cast(?MODULE, {update_topic, NewTopic}).

init([]) ->
    InitialState = #{
        brokers => ["localhost:9092"],
        topic => "orders"
    },
    {ok, InitialState}.

handle_call(get_config, _From, State) ->
    {reply, State, State}.

handle_cast({update_topic, NewTopic}, State) ->
    NewState = maps:put(topic, NewTopic, State),
    {noreply, NewState}.

handle_info(_Info, State) -> {noreply, State}.
terminate(_Reason, _State) -> ok.
code_change(_OldVsn, State, _Extra) -> {ok, State}.

Remember: A GenServer is not a database. It is a single-threaded process managing state in memory. Use it as a manager or coordinator, not as a replacement for PostgreSQL or ETS tables!

18. When Should an Erlang Developer Use GenServer?

Ideal Use Cases:

Stateful Workers (e.g., shopping cart process)
Connection Pool Managers (e.g., DB pool)
Rate Limiters & Token Buckets
In-memory Caches
Periodic Task Schedulers

When NOT to use GenServer:

Pure stateless functions (e.g., formatting strings, math formulas).
Extremely hot data access bottlenecks where an ETS table or lock-free structure is better suited.

19. Common Beginner Mistakes

Confusing call and cast: Using cast when you actually need data back from the process.
Thinking GenServer is a Database: Storing millions of records in a single GenServer's state will slow down message processing.
Forgetting to Return New State: Returning {noreply, State} instead of {noreply, State + 1} will silently drop your updates!
Putting Heavy Business Logic in Callbacks: Keep callbacks fast! If a callback takes 10 seconds, all other incoming messages sit stuck in the mailbox queue.
Misunderstanding Registration: Forgetting `{local, ?MODULE}` means you'll have to pass PIDs around manually.

20. GenServer Cheat Sheet

Start Process:
gen_server:start_link({local, ?MODULE}, ?MODULE, Args, Options)

Synchronous Call:
gen_server:call(?MODULE, Request)

Asynchronous Cast:
gen_server:cast(?MODULE, Request)

Stop Process:
gen_server:stop(?MODULE)

21. Final Mental Model & What You Should Remember

The Ultimate Mental Model: Think of a GenServer as a long-running background Erlang process wrapping a state variable. OTP manages the infinite message loop and network protocols. Your job is simply to write callback functions defining how state transitions occur when a message arrives.

Let's review this core startup call one last time in plain English:

gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).

"Hey OTP, start a supervised GenServer process. Register it locally under the current module's name. Look inside this same module for callbacks, pass an empty argument list to init/1, and use default options."

What You Should Remember:

Processes are lightweight isolated units that talk via messages.
PIDs are dynamic addresses; Registered Names let you reference processes predictably.
GenServer handles the heavy lifting of message loops and state.
handle_call is for synchronous responses, handle_cast is for asynchronous fire-and-forget.
Supervisors use start_link connections to catch crashes and auto-restart your processes.

Comments