otp-essentials

OTP Essentials

RULES — Follow these with no exceptions

1. Always use @impl true before GenServer/Agent callbacks (init, handle_call, handle_cast, handle_info, terminate)
2. Keep init/1 fast — no blocking calls, no DB queries; use handle_continue for expensive setup
3. Use GenServer.call for request/response, GenServer.cast for fire-and-forget — never cast when you need a result
4. Always define a public API wrapping GenServer calls — callers should never use GenServer.call(pid, ...) directly
5. Use Task.async/Task.await with bounded timeouts — never Task.async without a corresponding Task.await or Task.yield
6. Name processes via Registry, not atoms — atom table is finite and never garbage collected
7. Supervisors own process lifecycle — never start unsupervised long-running processes

---

GenServer

Public API Pattern

Always wrap GenServer calls behind a public module API. Callers should not know they're talking to a GenServer.

# Bad — leaks GenServer implementation to callers
GenServer.call(MyApp.Cache, {:get, key})

# Good — public API hides the GenServer
defmodule MyApp.Cache do
  use GenServer

  # --- Public API ---

  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)
    GenServer.start_link(__MODULE__, opts, name: name)
  end

  def get(key, server \\ __MODULE__) do
    GenServer.call(server, {:get, key})
  end

  def put(key, value, server \\ __MODULE__) do
    GenServer.cast(server, {:put, key, value})
  end

  # --- Callbacks ---

  @impl true
  def init(_opts) do
    {:ok, %{}}
  end

  @impl true
  def handle_call({:get, key}, _from, state) do
    {:reply, Map.get(state, key), state}
  end

  @impl true
  def handle_cast({:put, key, value}, state) do
    {:noreply, Map.put(state, key, value)}
  end
end

Fast Init with handle_continue

Never block in init/1. Use handle_continue for expensive setup.

# Bad — blocks the supervisor while loading data
@impl true
def init(opts) do
  data = MyApp.Repo.all(MyApp.Item)  # Blocks!
  {:ok, %{items: data}}
end

# Good — returns immediately, loads data asynchronously
@impl true
def init(opts) do
  {:ok, %{items: []}, {:continue, :load_data}}
end

@impl true
def handle_continue(:load_data, state) do
  data = MyApp.Repo.all(MyApp.Item)
  {:noreply, %{state | items: data}}
end