statig

States are methods in your impl block decorated with #[state]. When an event is handled, the method receives the event as an argument. Every state method must return an Outcome<State>, which determines the next step in the state machine lifecycle:

• Handled: The event was processed, and the machine remains in the current state.
• Transition(State): The machine transitions to the specified new state.
• Super: The event is not handled by the current state and is deferred to its parent superstate.

#[state]
fn led_on(event: &Event) -> Outcome<State> {
    Transition(State::led_off())
}

The #[state_machine] proc-macro is a code generator. It parses your impl blocks and derives the necessary boilerplate to make the state machine functional.

Key characteristics:

• It does not change your existing code; it simply adds generated code to your source file.
• It is used instead of a derive macro because Rust currently only allows derive macros on enums and structs, whereas statig needs to operate on impl blocks.
• You can avoid the macro entirely by writing the State and Superstate trait implementations by hand.

Statig supports hierarchical state machines. You can define a hierarchy by using the superstate argument in the #[state] attribute. A state can defer an event to its parent by returning Outcome::Super. Superstates themselves are defined using the #[superstate] attribute and can also have their own superstates.

#[state(superstate = "blinking")]
fn led_on(event: &Event) -> Outcome<State> {
    match event {
        Event::TimerElapsed => Transition(State::led_off()),
        Event::ButtonPressed => Super // Defer to 'blinking'
    }
}

#[superstate]
fn blinking(event: &Event) -> Outcome<State> {
    match event {
        Event::ButtonPressed => Transition(State::not_blinking()),
        _ => Super
    }
}

By enabling the async feature, you can define async fn for your states and actions. The #[state_machine] macro will automatically detect these and generate an async state machine. When using async, you must .await the .handle() calls.

#[state_machine(initial = "State::led_on()")]
impl Blinky {
    #[state]
    async fn led_on(event: &Event) -> Outcome<State> {
        // ...
    }
}

async fn main() {
    let mut state_machine = Blinky::default().state_machine();
    state_machine.handle(&Event::TimerElapsed).await;
}

To create a state machine, implement a struct and use the #[state_machine] attribute on its impl block. You must specify an initial state. Each state is defined as a method marked with #[state]. The macro generates a state_machine() method for your struct which returns a state machine instance that can process events via .handle().

#[derive(Default)]
pub struct Blinky;

pub enum Event {
    TimerElapsed,
    ButtonPressed
}

#[state_machine(initial = "State::led_on()", ...)]
impl Blinky {
    #[state]
    fn led_on(event: &Event) -> Outcome<State> {
        match event {
            Event::TimerElapsed => Transition(State::led_off()),
            _ => Super
        }
    }
    // ... other states
}

fn main() {
    let mut state_machine = Blinky::default().state_machine();
    state_machine.handle(&Event::TimerElapsed);
}

If the serde feature is enabled, state machines can be serialized and deserialized.

Important Lifecycle Note:

• An InitializedStateMachine serializes its state and storage.
• When deserialized, it results in an UninitializedStateMachine.
• You must call .init() or .init_with_context() on the deserialized UninitializedStateMachine to restore the machine to a functional, initialized state.

An UninitializedStateMachine<M> represents a state machine that has been constructed but whose entry actions have not yet been executed. To transition to an InitializedStateMachine<M>, you must call one of the following:

• init(): Consumes the uninitialized machine and returns an InitializedStateMachine using a default context ().
• init_with_context(context): Consumes the uninitialized machine and returns an InitializedStateMachine using the provided context.

Note that UninitializedStateMachine can be deserialized (if serde is enabled), but it must be initialized before it can be used to handle events.

let uninitialized = Blinky::default().uninitialized_state_machine();

// Transition to InitializedStateMachine
let mut initialized = uninitialized.init_with_context(&mut my_context);

A StateMachine<M> is a wrapper around your state machine logic that tracks whether it has been initialized.

• Lazy Initialization: If you call handle() or handle_with_context() on a StateMachine that hasn't been initialized yet, it will automatically call the internal initialization logic (executing entry actions for the initial state) before processing the event.
• Manual Initialization: You can force initialization by calling init() or init_with_context(context).

// The first handle() call triggers initialization automatically
state_machine.handle(&event);