otp-essentials

Files (1)

• SKILL.md

SKILL.md (first lines)

# OTP Essentials

Use before any GenServer, Supervisor, Task, Agent, Registry, or ETS work.

Processes **isolate and schedule work**. Modules organize code. Put business logic in pure modules; call them from thin callbacks.


## Quick Reference

| Concern | Do this |
|---------|---------|
| Process purpose | Concurrency / state / isolation — not module layout |
| Callbacks | Thin; pure modules compute |
| Startup I/O | `handle_continue`, not blocking `init/1` |
| Naming | Registry, not dynamic atoms |
| Batch tasks | Handle `async_stream` `{:exit, _}` |
| ETS | `:protected`; writes via owner |


## RULES — Follow these with no exceptions

**1.** **Processes are not modules** — never invent a GenServer just to “group functions”
**2.** **Thin callbacks** — `handle_call` / `handle_cast` / `handle_info` / `perform` only coordinate; pure code computes
**3.** **Fast `init/1`** — defer heavy work with `{:ok, state, {:continue, term}}`
**4.** **Public API module** — callers use `MyApp.Foo.do_thing/1`, never raw `GenServer.call/2`
**5.** **`@impl true`** on every callback
**6.** **Supervise everything long-lived** — no orphan processes
**7.** **Registry over dynamic atoms** for process names
**8.** **ETS**: owner process + `:protected` (or deliberate design); reads can bypass GenServer; writes serialized
**9.** **Handle `async_stream` exits** — match `{:ok, _}` and `{:exit, reason}`
**10.** **Let it crash** under a supervisor — avoid blanket `try/rescue` in callbacks

## Thin GenServer (FCIS)

❌ **Bad:** business logic inside the callback

```elixir
@impl true
def handle_call({:quote, items}, _from, state) do
  total =
    Enum.reduce(items, 0, fn item, acc ->
      if item.active, do: acc + item.price, else: acc
    end)

  {:reply, total, state}
end
```

✅ **Good:** pure module + thin callback

```elixir
defmodule MyApp.Pricing do
  def quote(items), do: Enum.reduce(items, 0, &(&1.price + &2))
end

defmodule MyApp.QuoteServer do
  use GenServer

  def start_link(opts), do: GenServer.start_link(__MODULE__, opts, name: __MODULE__)
  def quote(items), do: GenServer.call(__MODULE__, {:quote, items})

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

  @impl true
  def handle_call({:quote, items}, _from, state) do
    {:reply, MyApp.Pricing.quote(items), state}
  end
end
```

## GenServer skeleton

```elixir
defmodule MyApp.Counter do
  use GenServer

  # --- Client API ---
  def start_link(opts \\ []), do: GenServer.start_link(__MODULE__, 0, Keyword.put_new(opts, :name, __MODULE__))
  def value, do: GenServer.call(__MODULE__, :value)
  def increment, do: GenServer.cast(__MODULE__, :increment)

  # --- Server ---
  @impl true
  def init(count), do: {:ok, count}

  @impl true
  def handle_call(:value, _from, count), do: {:reply, count, count}

  @impl true
  def handle_cast(:increment, count), do: {:noreply, count + 1}
end
```

| Call style | When |
|------------|------|
| `call` | Need a reply or ordering with backpressure |
| `cast` | Fire-and-forget; client must not depend on completion |
| `handle_info` | Messages from monitors, timers, other processes |

## `handle_continue` for heavy startup

❌ **Bad:** block `init/1` with I/O

```elixir
@impl true
def init(opts) do
  {:ok, %{data: Loader.load!(opts)}}  # delays process start / supervision
end
```

✅ **Good:** continue after the process is up

```elixir
@impl true
def init(opts) do
  {:ok, %{opts: opts}, {:continue, :load}}
end

From igmarin/elixir-phoenix-skills, MIT.

More from igmarin/elixir-phoenix-skills