👁 Image
ZeroAlloc.StateMachine 1.5.1

ZeroAlloc.StateMachine

👁 NuGet
👁 Build
👁 AOT
👁 GitHub Sponsors

Source-generated, zero-allocation finite state machines for .NET.

Add [StateMachine] and [Transition<TState, TTrigger>] attributes to a partial class or struct. A Roslyn source generator emits a TryFire(TTrigger) method as a switch expression over (TState, TTrigger) tuples — no dictionary, no delegate dispatch, no heap allocation on the transition path. AOT-safe.

Quick start

dotnet add package ZeroAlloc.StateMachine

public enum State { Idle, Pending, Done }
public enum Trigger { Submit, Pay }

[StateMachine(InitialState = nameof(State.Idle))]
[Transition<State, Trigger>(From = State.Idle, On = Trigger.Submit, To = State.Pending)]
[Transition<State, Trigger>(From = State.Pending, On = Trigger.Pay, To = State.Done)]
[Terminal<State>(State = State.Done)]
public partial class OrderMachine { }

var machine = new OrderMachine();
machine.TryFire(Trigger.Submit); // true — Idle → Pending
machine.Current; // State.Pending
machine.TryFire(Trigger.Pay); // true — Pending → Done
machine.TryFire(Trigger.Submit); // false — Done has no outgoing transitions

Performance

Head-to-head vs Stateless 5.15 (the de-facto state-machine library in .NET). .NET 10.0.7, BenchmarkDotNet v0.14.0.

Stateless walks a Dictionary<TTrigger, StateRepresentation> on every fire and allocates trigger/transition info objects. ZA emits a switch expression over (State, Trigger) at compile time — single jump-table lookup, zero allocation on the dispatch path. The Fire-valid row also includes a per-iteration machine reset for both libraries; ZA's reset is one allocation because configuration is compile-time, while Stateless's reset includes its fluent Configure().Permit() rebuild — see docs/performance.md for the full breakdown.

Full methodology + self-benchmark: docs/performance.md.

Features

Attribute overview

[StateMachine]

[StateMachine(InitialState = nameof(State.Idle), Concurrent = false)]
public partial class MyMachine { }

[Transition<TState, TTrigger>]

[Transition<State, Trigger>(From = State.Idle, On = Trigger.Submit, To = State.Pending, When = false)]

[Terminal<TState>]

[Terminal<State>(State = State.Done)]

Marks a state as an intentional sink (no outgoing transitions). Silences ZSM0002.

Generated code

For each annotated type the generator emits one file alongside the user's source:

// <auto-generated />
partial class OrderMachine
{
 private State _state = State.Idle;
 public State Current => _state;

 public bool TryFire(Trigger trigger)
 => (Current, trigger) switch
 {
 (State.Idle, Trigger.Submit) => Fire(State.Idle, State.Pending, trigger),
 (State.Pending, Trigger.Pay) => Fire(State.Pending, State.Done, trigger),
 _ => false
 };

 private bool Fire(State from, State to, Trigger trigger) { ... }

 // Partial hook stubs — implement what you need, leave the rest
 partial void OnExitIdle(Trigger on);
 partial void OnExitPending(Trigger on);
 partial void OnEnterPending(State from);
 partial void OnEnterDone(State from);
}

Hooks

public partial class OrderMachine
{
 partial void OnExitIdle(Trigger on)
 => Console.WriteLine($"Leaving Idle via {on}");

 partial void OnEnterDone(State from)
 => Console.WriteLine($"Order complete, came from {from}");
}

Guards

[Transition<State, Trigger>(From = State.Pending, On = Trigger.Pay, To = State.Done, When = true)]
public partial class OrderMachine
{
 public bool HasBalance { get; set; }

 // Generator emits: private partial bool GuardPay(State from, Trigger on);
 private partial bool GuardPay(State from, Trigger on) => HasBalance;
}

Concurrent mode

[StateMachine(InitialState = nameof(State.Idle), Concurrent = true)]
[Transition<State, Trigger>(From = State.Idle, On = Trigger.Start, To = State.Running)]
public partial class WorkerMachine { }

State is stored as volatile long. TryFire uses a CAS loop — safe for concurrent callers. Guards are not generated in concurrent mode (TOCTOU risk).

Diagnostics

Documentation

Full docs live in docs/:

• Getting Started
• Attribute Reference
• Source Generator
• Testing
• AOT & Trimming
• Performance
• Core concepts: States & Triggers · Transitions · Concurrent Mode
• Guides: Guards · Entry/Exit Actions · Terminal States · Circuit Breaker Example

License

MIT