Concurrency & OTP /docs/fsm-guide

FSM Guide

FSM Programming Guide

fsm is an auto-preluded standard-library macro. It expands to an ordinary lift module with a checked gen_statem callback surface; the compiler does not contain a separate FSM parser or object class.

Std.Fsm declares two fsm macros over one shared callback floor:

  • The transition graph surface ( fsm Name with Data ) — a graph of From --Event--> To rows, verified at compile time and compiled to a total decide/3 . This is the preferred surface for anything shaped like a state machine, and the one that derives a full typed send / start API.
  • The structured event-body surface ( fsm Name with state / events ) — a lower-level shape that maps event patterns directly to callback results (or, in its typed form, to FsmAction values). Use it when you want to write a gen_statem callback body by hand, or need the enclosing module to see the state/event type names.

Both require use Std.Fsm . A bare module name is relative to its lexical owner; a dotted name is absolute within the Cure source namespace. Source never needs to spell the emitter-owned Cure. prefix.

Defining An FSM

The transition graph is the preferred surface:

use Std.Fsm

fsm Turnstile with Int
  Locked --Coin--> Unlocked
    update data + 1
  Unlocked --Push--> Locked
  Unlocked --Coin--> Unlocked
    update data + 1
  Locked --Push--> Locked

with Int declares the machine's data type — any Cure type works here, including a record or a Tuple(...) , not just a primitive. The macro catalogs every endpoint into a nominal State type ( Locked | Unlocked ) and every label into a nominal Event type ( Coin | Push ). Without an explicit initial row (below), the source state of the first written edge is the initial state; a wildcard row's source ( * ) is never eligible for this.

An edge preserves data unless it has an indented update expression. The expression is checked as the declared data type and may refer to data ; the target state is already fixed by the edge and is not repeated in callback tuples.

Record data uses Cure's ordinary typed record-update syntax. Fields not named after the bar are preserved:

use Std.Fsm

rec TurnstileData
  coins: Int
  pushes: Int
  enabled: Bool

fsm Turnstile with TurnstileData
  Locked --Coin--> Unlocked
    update TurnstileData{
      data
      | coins: data.coins + 1,
      enabled: true
    }
  Unlocked --Push--> Locked
    update TurnstileData{data | pushes: data.pushes + 1}
  Unlocked --Coin--> Unlocked
    update TurnstileData{data | coins: data.coins + 1}
  Locked --Push--> Locked

The | may instead occupy its own line before the first field; both layouts parse as the same typed record update, and either may update more than one field at once.

Why It Is Checked

Because the transition table is a declaration rather than a callback body, the compiler can verify properties that a hand-written gen_statem cannot express:

  • every event is declared for every state it can arrive in, or explicitly wildcarded;
  • the generated decide/3 is total over the declared state/event product;
  • update expressions are checked against the declared data type.

The Structured Surface

The lower-level form maps event patterns directly to callback results, and is what the tutorial shows:

fsm Turnstile
  state Int
  events
    Coin -> :keep_state_and_data

Each event branch is checked as an FsmAction ( Keep , Next , or Stop ). Transition tables are a library-level macro over the same generated gen_statem substrate rather than compiler syntax.

See Supervision for the surrounding actor and supervisor vocabulary, and Applications for wiring an FSM into a release.