State machines

The statemachine header (aliases state, fsm) draws states as stadium pills and transitions as labelled arrows between them. A node named start or initial becomes a filled circle; end or final becomes a stop marker.

statemachine
start -> Idle
Idle -> Loading : fetch
Loading -> Ready : ok
Loading -> Idle : error
Ready -> end : done

A filled start marker, labelled transitions, and a stop marker.

Start and end markers#

The pseudo-states are matched by name. start, begin, and initial all draw the entry dot; end, final, stop, and done all draw the exit marker. Everything else is a normal state.

statemachine
initial -> Connecting
Connecting -> Online : connected
Connecting -> Offline : timeout
Online -> Offline : lost
Offline -> Connecting : retry
Online -> stop : quit

Transitions#

A transition is an edge, and the text after : is its trigger or guard. Several transitions can leave one state, one per line, each with its own label. (A state that transitions to itself is a self-edge, which the canvas does not draw; route the failure through a distinct state instead, as Locked → Alarm does below.)

statemachine
start -> Locked
Locked -> Alarm : 3 wrong PINs
Alarm -> Locked : reset
Locked -> Unlocked : correct PIN
Unlocked -> Locked : lock
Unlocked -> end : shutdown

A failed attempt routes through a distinct Alarm state rather than looping on Locked.

The lifecycle of a background job, from queued to a terminal state.

statemachine
title: Job lifecycle

start -> Queued
Queued -> Running : worker picks up
Running -> Succeeded : ok
Running -> Failed : error
Failed -> Queued : retry
Failed -> Dead : max retries
Succeeded -> end
Dead -> end

An order state machine with cancellation paths.

statemachine
title: Order status

start -> Pending
Pending -> Paid : payment ok
Pending -> Cancelled : timeout
Paid -> Shipped : dispatch
Paid -> Refunded : cancel
Shipped -> Delivered : received
Delivered -> end
Cancelled -> end
Refunded -> end