ZeroAlloc.StateMachine 1.1.1

ZeroAlloc.StateMachine

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

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