Statig

https://docs.rs/statig/latest/
Admin
Statig is a Rust crate for designing event-driven systems using hierarchical state machines,...
Tokens:29,390
Snippets:212
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure state attributes

Source: https://docs.rs/statig/latest/statig/attr.state.html

Examples of various configuration attributes available for the state macro.

```rust
#[state(name = "CustomStateName")]
```

```rust
#[state(superstate = "superstate_name")]
```

```rust
#[state(entry_action = "entry_action_name")]
```

```rust
#[state(exit_action = "exit_action_name")]
```

```rust
#[state(local_storage("field_name_a: FieldTypeA", "field_name_b: FieldTypeB"))]
```

--------------------------------

### Define a Blinky State Machine

Source: https://docs.rs/statig/latest/index.html

A complete example of a state machine using the state_machine macro to handle timer and button events.

```rust
#[derive(Default)]
pub struct Blinky;

pub enum Event {
    TimerElapsed,
    ButtonPressed
}

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

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

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

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

fn main() {
    let mut state_machine = Blinky::default().state_machine();

    state_machine.handle(&Event::TimerElapsed);
    state_machine.handle(&Event::ButtonPressed);
}
```

--------------------------------

### state

Source: https://docs.rs/statig/latest/statig/awaitable/struct.StateMachine.html

Get the current state of the state machine.

```APIDOC
## pub fn state(&self) -> &M::State

### Description
Get the current state.
```

--------------------------------

### inner

Source: https://docs.rs/statig/latest/statig/awaitable/struct.StateMachine.html

Get a reference to the StateMachine’s underlying type.

```APIDOC
## pub fn inner(&self) -> &M

### Description
Get a reference to the StateMachine’s underlying type.
```

--------------------------------

### init

Source: https://docs.rs/statig/latest/statig/awaitable/struct.UninitializedStateMachine.html

Initializes the state machine by executing all entry actions towards the initial state, consuming the uninitialized instance.

```APIDOC
## pub async fn init(self) -> InitializedStateMachine<M>

### Description
Initializes the state machine by executing all entry actions towards the initial state. This method consumes the uninitialized state machine.

### Parameters
- **self** - Required - The uninitialized state machine instance.

### Returns
- **InitializedStateMachine<M>** - The resulting initialized state machine.
```

--------------------------------

### init_with_context

Source: https://docs.rs/statig/latest/statig/awaitable/struct.StateMachine.html

Explicitly initialize the state machine using a provided context.

```APIDOC
## pub async fn init_with_context(&mut self, context: &mut M::Context<'_>)

### Description
Explicitly initialize the state machine. If the state machine is already initialized this is a no-op.
```

--------------------------------

### handle

Source: https://docs.rs/statig/latest/statig/awaitable/struct.StateMachine.html

Handle an event. If the state machine is uninitialized, it will be initialized before handling the event.

```APIDOC
## pub async fn handle(&mut self, event: &M::Event<'_>)

### Description
Handle an event. If the state machine is still uninitialized, it will be initialized before handling the event.
```

--------------------------------

### Initialize a state machine

Source: https://docs.rs/statig/latest/statig/awaitable/struct.UninitializedStateMachine.html

Demonstrates consuming an uninitialized state machine to produce an initialized one.

```rust
let uninitialized_state_machine = Blinky::default().uninitialized_state_machine();

// The uninitialized state machine is consumed to create the initialized
// state machine.
let initialized_state_machine = uninitialized_state_machine.init().await;
```

--------------------------------

### init

Source: https://docs.rs/statig/latest/statig/awaitable/struct.StateMachine.html

Explicitly initialize the state machine. If the state machine is already initialized, this is a no-op.

```APIDOC
## pub async fn init(&mut self)

### Description
Explicitly initialize the state machine. If the state machine is already initialized this is a no-op.
```

--------------------------------

### Implement state machine logic

Source: https://docs.rs/statig/latest/src/statig/blocking/inner.rs.html

Methods for initializing the state machine, handling events, and performing transitions between states.

```rust
impl<M> Inner<M>
where
    M: IntoStateMachine,
    M::State: State<M>,
    for<'sub> M::Superstate<'sub>: Superstate<M>,
{
    /// Initialize the state machine by executing all entry actions towards the initial state.
    pub(crate) fn init_with_context(&mut self, context: &mut M::Context<'_>) {
        let enter_levels = self.state.depth();
        self.state
            .enter(&mut self.shared_storage, context, enter_levels);
    }

    /// Handle the given event.
    pub(crate) fn handle_with_context(
        &mut self,
        event: &M::Event<'_>,
        context: &mut M::Context<'_>,
    ) {
        let outcome = self.state.handle(&mut self.shared_storage, event, context);
        match outcome {
            Outcome::Super => {}
            Outcome::Handled => {}
            Outcome::Transition(state) => self.transition(state, context),
        }
    }

    /// Transition from the current state to the given target state.
    pub(crate) fn transition(&mut self, mut target: M::State, context: &mut M::Context<'_>) {
        M::before_transition(&mut self.shared_storage, &target, &self.state, context);

        // Get the transition path we need to perform from one state to the next.
        let (exit_levels, enter_levels) = self.state.transition_path(&mut target);

        // Perform the exit from the previous state towards the common ancestor state.
        self.state
            .exit(&mut self.shared_storage, context, exit_levels);

        // Update the state.
        core::mem::swap(&mut self.state, &mut target);

        // Perform the entry actions from the common ancestor state into the new state.
        self.state
            .enter(&mut self.shared_storage, context, enter_levels);

        M::after_transition(&mut self.shared_storage, &target, &self.state, context);
    }
}
```

--------------------------------

### UninitializedStateMachine::init_with_context

Source: https://docs.rs/statig/latest/src/statig/blocking/state_machine.rs.html

Initializes the state machine by executing all entry actions towards the initial state, providing a mutable reference to the state machine's context.

```APIDOC
## fn init_with_context(self, context: &mut M::Context<'_>) -> InitializedStateMachine<M>

### Description
Initializes the state machine by executing all entry actions towards the initial state, allowing the injection of a context object required for initialization.

### Parameters
- **context** (&mut M::Context<'_>) - Required - A mutable reference to the context required by the state machine.

### Returns
- **InitializedStateMachine<M>** - The initialized state machine instance.
```

--------------------------------

### Implement state machine logic

Source: https://docs.rs/statig/latest/src/statig/awaitable/inner.rs.html

Methods for initializing, handling events, and performing transitions within the state machine.

```rust
impl<M> Inner<M>
where
    M: IntoStateMachine,
    M::State: State<M> + 'static,
    for<'sub> M::Superstate<'sub>: Superstate<M>,
{
    pub(crate) async fn init_with_context(&mut self, context: &mut M::Context<'_>) {
        let enter_levels = self.state.depth();
        self.state
            .enter(&mut self.shared_storage, context, enter_levels)
            .await;
    }

    pub(crate) async fn handle_with_context(
        &mut self,
        event: &M::Event<'_>,
        context: &mut M::Context<'_>,
    ) {
        let outcome = self
            .state
            .handle(&mut self.shared_storage, event, context)
            .await;
        match outcome {
            Outcome::Super => {}
            Outcome::Handled => {}
            Outcome::Transition(state) => self.transition(state, context).await,
        }
    }

    /// Transition from the current state to the given target state.
    pub(crate) async fn transition(&mut self, mut target: M::State, context: &mut M::Context<'_>) {
        M::before_transition(&mut self.shared_storage, &self.state, &target, context).await;

        // Get the transition path we need to perform from one state to the next.
        let (exit_levels, enter_levels) = self.state.transition_path(&mut target);

        // Perform the exit from the previous state towards the common ancestor state.
        self.state
            .exit(&mut self.shared_storage, context, exit_levels)
            .await;

        // Update the state.
        core::mem::swap(&mut self.state, &mut target);

        // Perform the entry actions from the common ancestor state into the new state.
        self.state
            .enter(&mut self.shared_storage, context, enter_levels)
            .await;

        M::after_transition(&mut self.shared_storage, &target, &self.state, context).await;
    }
}
```

--------------------------------

### Define Entry and Exit Actions

Source: https://docs.rs/statig/latest/index.html

Actions are executed upon entering or leaving a state during a transition.

```rust
#[state(entry_action = "enter_led_on", exit_action = "exit_led_on")]
fn led_on(event: &Event) -> Outcome<State> {
    Transition(State::led_off())
}

#[action]
fn enter_led_on() {
    println!("Entered on");
}

#[action]
fn exit_led_on() {
    println!("Exited on");
}
```

--------------------------------

### state_machine

Source: https://docs.rs/statig/latest/statig/awaitable/trait.IntoStateMachineExt.html

Creates a state machine that will be lazily initialized.

```APIDOC
## fn state_machine(self) -> StateMachine<Self>

### Description
Creates a state machine that will be lazily initialized.

### Signature
`fn state_machine(self) -> StateMachine<Self> where Self: Sized`
```

--------------------------------

### State Transition Actions

Source: https://docs.rs/statig/latest/src/statig/blocking/state.rs.html

Recursive methods for executing entry and exit actions across state hierarchies.

```rust
    /// entry actions while going back down to the current state.
    fn enter(&mut self, shared_storage: &mut M, context: &mut M::Context<'_>, levels: usize) {
        match levels {
            0 => (),
            1 => self.call_entry_action(shared_storage, context),
            _ => {
                if let Some(mut superstate) = self.superstate() {
                    superstate.enter(shared_storage, context, levels - 1);
                }
                self.call_entry_action(shared_storage, context);
            }
        }
    }

    /// Starting from the current state, climb a given amount of levels and execute all the
    /// the exit actions while going up to a certain superstate.
    fn exit(&mut self, shared_storage: &mut M, context: &mut M::Context<'_>, levels: usize) {
        match levels {
            0 => (),
            1 => self.call_exit_action(shared_storage, context),
            _ => {
                self.call_exit_action(shared_storage, context);
                if let Some(mut superstate) = self.superstate() {
                    superstate.exit(shared_storage, context, levels - 1);
                }
            }
        }
    }
}
```

--------------------------------

### InitializedStateMachine::handle

Source: https://docs.rs/statig/latest/src/statig/blocking/state_machine.rs.html

Handles an event for an initialized state machine.

```APIDOC
## pub fn handle(&mut self, event: &M::Event<'_>)

### Description
Processes the provided event within the context of the initialized state machine.

### Parameters
- **event** (&M::Event) - The event to be processed by the state machine.
```

--------------------------------

### handle

Source: https://docs.rs/statig/latest/statig/awaitable/struct.InitializedStateMachine.html

Handles the given event for the state machine.

```APIDOC
## pub async fn handle(&mut self, event: &M::Event<'_>)

### Description
Handles the given event for the state machine. This method is available when the state machine context is unit (()).

### Parameters
- **event** (&M::Event<'_>) - Required - The event to be processed by the state machine.
```

--------------------------------

### UninitializedStateMachine::init

Source: https://docs.rs/statig/latest/src/statig/awaitable/state_machine.rs.html

Initializes the state machine by executing all entry actions towards the initial state. This method consumes the uninitialized state machine and returns an InitializedStateMachine.

```APIDOC
## UninitializedStateMachine::init

### Description
Initializes the state machine by executing all entry actions towards the initial state. This method consumes the uninitialized state machine and returns an InitializedStateMachine.

### Signature
`pub async fn init(self) -> InitializedStateMachine<M>`

### Constraints
- `M: IntoStateMachine<Context<'ctx> = ()>`
- `M::State: State<M> + 'static`
- `for<'sub> M::Superstate<'sub>: Superstate<M>`
```

--------------------------------

### StateMachine Methods

Source: https://docs.rs/statig/latest/statig/blocking/struct.StateMachine.html

Methods available for interacting with the StateMachine instance.

```APIDOC
## pub fn init(&mut self)

### Description
Explicitly initialize the state machine. If the state machine is already initialized this is a no-op.

## pub fn init_with_context(&mut self, context: &mut M::Context<'_>)

### Description
Explicitly initialize the state machine with a provided context. If the state machine is already initialized this is a no-op.

## pub fn handle(&mut self, event: &M::Event<'_>)

### Description
Handle an event. If the state machine is still uninitialized, it will be initialized before handling the event.

## pub fn handle_with_context(&mut self, event: &M::Event<'_>, context: &mut M::Context<'_>)

### Description
Handle an event with a provided context. If the state machine is still uninitialized, it will be initialized before handling the event.

## pub fn state(&self) -> &M::State

### Description
Get the current state of the state machine.

## pub fn inner(&self) -> &M

### Description
Get a reference to the StateMachine’s underlying type.
```

--------------------------------

### Implement State Entry Actions

Source: https://docs.rs/statig/latest/src/statig/awaitable/state.rs.html

Executes entry actions while climbing up and down the state hierarchy based on the specified number of levels.

```rust
fn enter(
        &mut self,
        shared_storage: &mut M,
        context: &mut M::Context<'_>,
        mut levels: usize,
    ) -> impl Future<Output = ()> {
        async move {
            // For each level we need to enter, climb that number of levels and excecute
            // the superstate's entry action. We then decrement `levels` and again climb
            // up the tree and execute the next entry action. We keep doing this until
            // `levels` is equal to 1, which means the only entry action left to excecute
            // is the state's own.
            while levels > 1 {
                if let Some(mut superstate) = self.superstate() {
                    for _ in 2..levels {
                        superstate = match superstate.superstate() {
                            Some(superstate) => superstate,
                            None => break,
                        }
                    }
                    superstate.call_entry_action(shared_storage, context).await;
                }
                levels -= 1;
            }

            if levels == 1 {
                self.call_entry_action(shared_storage, context).await;
            }
        }
    }
```

--------------------------------

### step_with_context

Source: https://docs.rs/statig/latest/statig/awaitable/struct.InitializedStateMachine.html

Advances the state machine by one step using a provided context.

```APIDOC
## pub async fn step_with_context(&mut self, context: &mut M::Context<'_>)

### Description
Advances the state machine by one step using the provided context. This is equivalent to calling `handle_with_context((), context)` when the event type is unit (()).

### Parameters
- **context** (&mut M::Context<'_>) - Required - The mutable context to be used during the step.
```

--------------------------------

### Implement entry and exit actions

Source: https://docs.rs/statig/latest/index.html

Define logic to execute when entering or exiting specific states and superstates.

```rust
impl statig::State<Blinky> for State {

    ...

    fn call_entry_action(&mut self, blinky: &mut Blinky, context: &mut ()) {
        match self {
            State::LedOn { counter } => blinky.enter_led_on(counter),
            State::LedOff { counter } => blinky.enter_led_off(counter),
            State::NotBlinking => blinky.enter_not_blinking()
        }
    }

    fn call_exit_action(&mut self, blinky: &mut Blinky, context: &mut ()) {
        match self {
            State::LedOn { counter } => blinky.exit_led_on(counter),
            State::LedOff { counter } => blinky.exit_led_off(counter),
            State::NotBlinking => blinky.exit_not_blinking()
        }
    }
}

impl statig::Superstate<Blinky> for Superstate {

    ...

    fn call_entry_action(&mut self, blinky: &mut Blinky, context: &mut ()) {
        match self {
            Superstate::Blinking { counter } => blinky.enter_blinking(counter),
        }
    }

    fn call_exit_action(&mut self, blinky: &mut Blinky, context: &mut ()) {
        match self {
            Superstate::Blinking { counter } => blinky.exit_blinking(counter),
        }
    }
}
```

--------------------------------

### TransitionHook Implementations

Source: https://docs.rs/statig/latest/statig/awaitable/trait.TransitionHook.html

Implementations of TransitionHook for asynchronous functions with varying parameter signatures.

```rust
impl<T, F> TransitionHook<T, ((), ())> for F
where T: IntoStateMachine, F: AsyncFnOnce(&mut T, &T::State, &T::State, &mut T::Context<'_>),
```

```rust
impl<T, F> TransitionHook<T, ((),)> for F
where T: IntoStateMachine, F: AsyncFnOnce(&mut T, &T::State, &T::State),
```

--------------------------------

### Statig Library Configuration

Source: https://docs.rs/statig/latest/src/statig/lib.rs.html

The initial module configuration for the Statig library, including feature flags and internal module declarations.

```rust
1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![cfg_attr(not(doctest), doc = include_str!(concat!("../", core::env!("CARGO_PKG_README"))))]
3#![no_std]
4#![allow(incomplete_features)]
5
6mod outcome;
7mod state_or_superstate;
8
9/// Macro for deriving the state and superstate enum.
10///
11/// By parsing the underlying `impl` block and searching for methods with the
12/// `state`, `superstate` or `action` attribute, the `state_machine` macro can
13/// derive the state and superstate enums. By default these will be given the
14/// names '`State`' and '`Superstate`'. Next to that the macro will also
15/// implement the [`State`](crate::blocking::State) trait for the state enum and the
16/// [`Superstate`](crate::blocking::Superstate) trait for the superstate enum.
17///
18/// To override the default configuration you can use the following attributes.
19///
20/// - `#[state_machine(state(name = "CustomStateName"))]`
21///
22///   Set the name of the state enum to a custom name.
23///
24///   _Default_: `State`
25///
26///   <br/>
27///
28/// - `#[state_machine(superstate(name = "CustomSuperstateName"))]`
29///
30///   Set the name of the superstate enum to a custom name.
31///
32///   _Default_: `Superstate`
33///
34///   <br/>
35///
36/// - `#[state_machine(state(derive(SomeTrait, AnotherTrait)))]`
37///
38///   Apply the derive macro with the passed traits to the state enum.
39///
40///   _Default_: `()`
41///
42///   <br/>
43///
44/// - `#[state_machine(superstate(derive(SomeTrait, AnotherTrait)))]`
45///
46///   Apply the derive macro with the passed traits to the superstate enum.
47///
48///   _Default_: `()`
49///
50///   <br/>
51#[cfg(feature = "macro")]
52#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
53pub use statig_macro::state_machine;
54
55/// Attribute for tagging a state.
56///
57/// This macro does nothing on its own but is detected by the `state_machine`
58/// macro when added to a method.
59///
60/// It accepts the following attributes:
61///
62/// - `#[state(name = "CustomStateName")]`
63///
64///   Set the name of the variant that will be part of the state enum.
65///
66///   <br/>
67///
68/// - `#[state(superstate = "superstate_name")]`
69///
70///   Set the superstate of the state.
71///
72///   <br/>
73///
74/// - `#[state(entry_action = "entry_action_name")]`
75///
76///   Set the entry action of the state.
77///
78///   <br/>
79///
80/// - `#[state(exit_action = "exit_action_name")]`
81///
82///   Set the exit action of the state.
83///
84///   <br/>
85///
86/// - `#[state(local_storage("field_name_a: FieldTypeA", "field_name_b: FieldTypeB"))]`
87///
88///   Add local storage to this state. These will be added as fields to the enum variant.
89///
90///   <br/>
91#[cfg(feature = "macro")]
92#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
93pub use statig_macro::state;
94
95/// Attribute for tagging a superstate.
96///
97/// This macro does nothing on its own but is detected by the `state_machine`
98/// macro when added to a method.
99///
100/// It accepts the following attributes:
101///
102/// - `#[superstate(name = "CustomSuperstateName")]`
103///
104///   Set the name of the variant that will be part of the state enum.
105///
106///   <br/>
107///
108/// - `#[superstate(superstate = "superstate_name")]`
109///
110///   Set the superstate of the superstate.
111///
112///   <br/>
113///
114/// - `#[superstate(entry_action = "entry_action_name")]`
115///
116///   Set the entry action of the superstate.
117///
118///   <br/>
119///
120/// - `#[superstate(exit_action = "exit_action_name")]`
121///
122///   Set the exit action of the superstate.
123///
124///   <br/>
125///
126/// - `#[superstate(local_storage("field_name_a: &'a mut FieldTypeA"))]`
127///
128///   Add local storage to this superstate. These will be added as fields to
129///   the enum variant. It is crucial to understand that superstates never own
130///   their data. Instead it is always borrowed from the underlying state or
131///   superstate. This means the fields should be references with an
132///   associated lifetime `'a`.
133///
134///   <br/>
135#[cfg(feature = "macro")]
136#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
137pub use statig_macro::superstate;
138
139/// Attribute for tagging an action.
140///
141/// This macro does nothing on its own but is detected by the `state_machine`
142/// macro when added to a method.
143#[cfg(feature = "macro")]
144#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
145pub use statig_macro::action;
146
147/// Prelude containing the necessary imports for use with macro.
148pub mod prelude {
149    #![allow(ambiguous_glob_reexports)]
150    #![allow(unused_imports)]
151
152    #[cfg(feature = "async")]
153    #[cfg_attr(docsrs, doc(cfg(feature = "async")))]
```

--------------------------------

### handle_with_context

Source: https://docs.rs/statig/latest/statig/awaitable/struct.InitializedStateMachine.html

Handles the given event for the state machine using a provided context.

```APIDOC
## pub async fn handle_with_context(&mut self, event: &M::Event<'_>, context: &mut M::Context<'_>)

### Description
Handles the given event for the state machine, allowing for external context to be passed and modified during event processing.

### Parameters
- **event** (&M::Event<'_>) - Required - The event to be processed.
- **context** (&mut M::Context<'_>) - Required - The mutable context to be used during event handling.
```

--------------------------------

### step / step_with_context

Source: https://docs.rs/statig/latest/src/statig/blocking/state_machine.rs.html

Advances the state machine by one step, typically used when the event type is unit ().

```APIDOC
## step / step_with_context

### Description
Executes a step in the state machine. `step` uses a default context, while `step_with_context` allows providing a custom context.

### Signatures
`pub fn step(&mut self)`
`pub fn step_with_context(&mut self, context: &mut M::Context<'_>)`
```

--------------------------------

### step

Source: https://docs.rs/statig/latest/statig/awaitable/struct.InitializedStateMachine.html

Advances the state machine by one step, equivalent to handling a unit event.

```APIDOC
## pub async fn step(&mut self)

### Description
Advances the state machine by one step. This is equivalent to calling `handle(())` when the event type is unit (()).
```

--------------------------------

### Implement Serde serialization and deserialization

Source: https://docs.rs/statig/latest/src/statig/blocking/inner.rs.html

Optional Serde support for serializing and deserializing the Inner state machine.

```rust
#[cfg(feature = "serde")]
impl<M> serde::Serialize for Inner<M>
where
    M: IntoStateMachine + serde::Serialize,
    M::State: serde::Serialize,
{
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct;

        let mut serializer = serializer.serialize_struct("StateMachine", 2)?;
        serializer.serialize_field("shared_storage", &self.shared_storage)?;
        serializer.serialize_field("state", &self.state)?;
        serializer.end()
    }
}

#[cfg(feature = "serde")]
/// A serialized state machine can only be deserialized into an [`UnInitializedStateMachine`] and can
/// then be initialized with [`init`](UnInitializedStateMachine::init).
impl<'de, M> serde::Deserialize<'de> for Inner<M>
where
    M: IntoStateMachine + serde::Deserialize<'de>,
    M::State: serde::Deserialize<'de>,
{
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use core::marker::PhantomData;

        enum Field {
            SharedStorage,
            State,
        }

        impl<'de> serde::Deserialize<'de> for Field {
            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
            where
                D: serde::Deserializer<'de>,
            {
                struct FieldVisitor;

                impl<'de> serde::de::Visitor<'de> for FieldVisitor {
                    type Value = Field;

                    fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
                        formatter.write_str("`shared_storage` or `state`")
                    }

                    fn visit_str<E>(self, value: &str) -> Result<Field, E>
                    where
```

--------------------------------

### uninitialized_state_machine

Source: https://docs.rs/statig/latest/statig/awaitable/trait.IntoStateMachineExt.html

Creates an uninitialized state machine that must be explicitly initialized with init.

```APIDOC
## fn uninitialized_state_machine(self) -> UninitializedStateMachine<Self>

### Description
Creates an uninitialized state machine that must be explicitly initialized with init.

### Signature
`fn uninitialized_state_machine(self) -> UninitializedStateMachine<Self>`
```

--------------------------------

### Use Async State Handlers

Source: https://docs.rs/statig/latest/index.html

Enable the async feature to define asynchronous state handlers and await event handling.

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

```rust
async fn main() {
    let mut state_machine = Blinky::default().state_machine();

    state_machine.handle(&Event::TimerElapsed).await;
    state_machine.handle(&Event::ButtonPressed).await;
}
```

--------------------------------

### Recursive Entry and Exit Actions

Source: https://docs.rs/statig/latest/src/statig/blocking/superstate.rs.html

Logic for traversing superstate hierarchies to execute entry and exit actions.

```rust
            0 => (),
            1 => self.call_entry_action(shared_storage, context),
            _ => {
                if let Some(mut superstate) = self.superstate() {
                    levels -= 1;
                    superstate.enter(shared_storage, context, levels);
                }
                self.call_entry_action(shared_storage, context);
            }
        }
    }

    /// Starting from the current superstate, climb a given amount of levels and execute all the
    /// the exit actions while going up to a certain superstate.
    fn exit(&mut self, shared_storage: &mut M, context: &mut M::Context<'_>, mut levels: usize) {
        match levels {
            0 => (),
            1 => self.call_exit_action(shared_storage, context),
            _ => {
                self.call_exit_action(shared_storage, context);
                if let Some(mut superstate) = self.superstate() {
                    levels -= 1;
                    superstate.exit(shared_storage, context, levels);
                }
            }
        }
    }
}
```

--------------------------------

### Implement standard traits for Inner

Source: https://docs.rs/statig/latest/src/statig/awaitable/inner.rs.html

Implementations for Clone, PartialEq, and Eq to support state machine management.

```rust
impl<M> Clone for Inner<M>
where
    M: IntoStateMachine + Clone,
    M::State: Clone,
{
    fn clone(&self) -> Self {
        Self {
            shared_storage: self.shared_storage.clone(),
            state: self.state.clone(),
        }
    }
}

impl<M> PartialEq for Inner<M>
where
    M: IntoStateMachine + PartialEq,
    M::State: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        self.shared_storage == other.shared_storage && self.state == other.state
    }
}

impl<M> Eq for Inner<M>
where
    M: IntoStateMachine + Eq,
    M::State: Eq,
{}
```

--------------------------------

### TransitionHook Implementations

Source: https://docs.rs/statig/latest/statig/blocking/trait.TransitionHook.html

Implementations of TransitionHook for function types.

```rust
impl<T, F> TransitionHook<T, ()> for F
where T: IntoStateMachine, F: Fn(&mut T, &T::State, &T::State),
```

```rust
impl<T, F> TransitionHook<T, (<T as IntoStateMachine>::Context<'_>,)> for F
where T: IntoStateMachine, F: Fn(&mut T, &T::State, &T::State, &mut T::Context<'_>),
```

--------------------------------

### Implement State and Superstate handlers

Source: https://docs.rs/statig/latest/index.html

Associate states and superstates with their respective handlers using the call_handler method.

```rust
impl statig::State<Blinky> for State {
    fn call_handler(&mut self, blinky: &mut Blinky, event: &Event, context: &mut ()) -> Outcome<Self> {
        match self {
            State::LedOn { counter } => blinky.led_on(counter, event),
            State::LedOff { counter } => blinky.led_off(counter, event),
            State::NotBlinking => blinky.not_blinking(event)
        }
    }
}

impl statig::Superstate<Blinky> for Superstate {
    fn call_handler(&mut self, blinky: &mut Blinky, event: &Event, context: &mut ()) -> Outcome<Self> {
        match self {
            Superstate::Blinking { counter } => blinky.blinking(counter, event),
        }
    }
}
```

--------------------------------

### Apply state_machine macro

Source: https://docs.rs/statig/latest/statig/attr.state_machine.html

Basic usage of the state_machine attribute macro. Requires the macro feature flag.

```rust
#[state_machine]
```

--------------------------------

### Implement Serde serialization

Source: https://docs.rs/statig/latest/src/statig/awaitable/inner.rs.html

Serialization support for the Inner struct when the serde feature is enabled.

```rust
#[cfg(feature = "serde")]
impl<M> serde::Serialize for Inner<M>
where
    M: IntoStateMachine + serde::Serialize,
    M::State: serde::Serialize,
{
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct;

        let mut serializer = serializer.serialize_struct("StateMachine", 2)?;
        serializer.serialize_field("shared_storage", &self.shared_storage)?;
        serializer.serialize_field("state", &self.state)?;
        serializer.end()
    }
}
```

--------------------------------

### Superstate Extensions

Source: https://docs.rs/statig/latest/src/statig/awaitable/superstate.rs.html

Provides helper methods for comparing states and calculating hierarchy depth.

```rust
/// Extensions for `Superstate` trait.
pub trait SuperstateExt<M>: Superstate<M>
where
    Self: Sized,
    M: IntoStateMachine,
    for<'sub> M::Superstate<'sub>: Superstate<M>,
{
    fn same_state(lhs: &M::Superstate<'_>, rhs: &M::Superstate<'_>) -> bool {
        use core::mem::{discriminant, transmute, Discriminant};

        // Generic associated types are invariant over any lifetime arguments, so the
        // compiler won't allow us to compare them directly. Instead we need to coerce them
        // to have the same lifetime by transmuting them to the same type.

        let lhs: Discriminant<M::Superstate<'_>> = unsafe { transmute(discriminant(lhs)) };
        let rhs: Discriminant<M::Superstate<'_>> = unsafe { transmute(discriminant(rhs)) };

        lhs == rhs
    }

    /// Get the depth of the current superstate.
    fn depth(&mut self) -> usize {
        match self.superstate() {
            Some(mut superstate) => superstate.depth() + 1,
            None => 1,
        }
    }

    /// Get the depth of the common ancestor of two states.
    fn common_ancestor_depth(
        mut source: M::Superstate<'_>,
        mut target: M::Superstate<'_>,
    ) -> usize {
        match source.depth().cmp(&target.depth()) {
            Ordering::Equal => match Self::same_state(&source, &target) {
                true => source.depth(),
                false => match (source.superstate(), target.superstate()) {
                    (Some(source), Some(target)) => Self::common_ancestor_depth(source, target),
                    _ => 0,
                },
            },
            Ordering::Greater => match source.superstate() {
                Some(superstate) => Self::common_ancestor_depth(superstate, target),
                None => 0,
            },
            Ordering::Less => match target.superstate() {
                Some(superstate) => Self::common_ancestor_depth(source, superstate),
                None => 0,
            },
        }
    }
}
```

--------------------------------

### Unit Type Implementation

Source: https://docs.rs/statig/latest/src/statig/awaitable/superstate.rs.html

Default implementation for when no superstates are required.

```rust
/// When no superstates are required, the user can pass the [`()`](unit) type.
impl<M> Superstate<M> for ()
where
    M: IntoStateMachine,
{
    fn call_handler(
        &mut self,
        _: &mut M,
        _: &M::Event<'_>,
        _: &mut M::Context<'_>,
    ) -> impl Future<Output = Outcome<M::State>> {
        core::future::ready(Outcome::Handled)
    }

    fn call_entry_action(&mut self, _: &mut M, _: &mut M::Context<'_>) -> impl Future<Output = ()> {
        core::future::ready(())
    }

    fn call_exit_action(&mut self, _: &mut M, _: &mut M::Context<'_>) -> impl Future<Output = ()> {
        core::future::ready(())
    }

    fn superstate(&mut self) -> Option<Self>
    where
        Self: Sized,
    {
        None
    }
}
```

--------------------------------

### Deserialize implementation for UninitializedStateMachine

Source: https://docs.rs/statig/latest/src/statig/awaitable/state_machine.rs.html

Implements serde::Deserialize for UninitializedStateMachine, requiring the state machine model and its state to also implement Deserialize.

```rust
#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
/// A serialized state machine can only be deserialized into an [`UninitializedStateMachine`] and can
/// then be initialized with [`init`](UninitializedStateMachine::init).
impl<'de, M> serde::Deserialize<'de> for UninitializedStateMachine<M>
where
    M: IntoStateMachine + serde::Deserialize<'de>,
    M::State: serde::Deserialize<'de>,
{
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let inner: Inner<M> = Inner::deserialize(deserializer)?;
        Ok(UninitializedStateMachine { inner })
    }
}
```

--------------------------------

### Implement Serde Visitor for Inner State Machine

Source: https://docs.rs/statig/latest/src/statig/awaitable/inner.rs.html

Defines a custom visitor to handle deserialization of the Inner struct from either sequences or maps.

```rust
150                        E: serde::de::Error,
151                    {
152                        match value {
153                            "shared_storage" => Ok(Field::SharedStorage),
154                            "state" => Ok(Field::State),
155                            _ => Err(serde::de::Error::unknown_field(value, FIELDS)),
156                        }
157                    }
158                }
159
160                deserializer.deserialize_identifier(FieldVisitor)
161            }
162        }
163
164        struct InnerVisitor<M>(PhantomData<M>);
165
166        impl<'de, M> serde::de::Visitor<'de> for InnerVisitor<M>
167        where
168            M: IntoStateMachine + serde::Deserialize<'de>,
169            M::State: serde::Deserialize<'de>,
170        {
171            type Value = Inner<M>;
172
173            fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
174                formatter.write_str("StateMachine")
175            }
176
177            fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
178            where
179                A: serde::de::SeqAccess<'de>,
180            {
181                let shared_storage = seq
182                    .next_element()?
183                    .ok_or_else(|| serde::de::Error::invalid_length(0, &self))?;
184                let state = seq
185                    .next_element()?
186                    .ok_or_else(|| serde::de::Error::invalid_length(1, &self))?;
187                let inner = Inner {
188                    shared_storage,
189                    state,
190                };
191                Ok(inner)
192            }
193
194            fn visit_map<V>(self, mut map: V) -> Result<Self::Value, V::Error>
195            where
196                V: serde::de::MapAccess<'de>,
197            {
198                let mut shared_storage = None;
199                let mut state = None;
200                while let Some(key) = map.next_key()? {
201                    match key {
202                        Field::SharedStorage => {
203                            if shared_storage.is_some() {
204                                return Err(serde::de::Error::duplicate_field("shared_storage"));
205                            }
206                            shared_storage = Some(map.next_value()?);
207                        }
208                        Field::State => {
209                            if state.is_some() {
210                                return Err(serde::de::Error::duplicate_field("state"));
211                            }
212                            state = Some(map.next_value()?);
213                        }
214                    }
215                }
216                let shared_storage = shared_storage
217                    .ok_or_else(|| serde::de::Error::missing_field("shared_storage"))?;
218                let state = state.ok_or_else(|| serde::de::Error::missing_field("state"))?;
219                let inner = Inner {
220                    shared_storage,
221                    state,
222                };
223                Ok(inner)
224            }
225        }
226
227        const FIELDS: &[&str] = &["shared_storage", "state"];
228        deserializer.deserialize_struct(
229            "StateMachine",
230            FIELDS,
231            InnerVisitor(PhantomData::default()),
232        )
233    }
234}
```

--------------------------------

### Implement State Exit Actions

Source: https://docs.rs/statig/latest/src/statig/awaitable/state.rs.html

Executes exit actions while climbing up the state hierarchy to a target superstate.

```rust
fn exit(
        &mut self,
        shared_storage: &mut M,
        context: &mut M::Context<'_>,
        mut levels: usize,
    ) -> impl Future<Output = ()> {
        async move {
            // First we need to excucute that state's own exit action.
            if levels >= 1 {
                self.call_exit_action(shared_storage, context).await;
            }

            // For each level we need to exit, climb up one level in the tree and
            // execute the superstate's exit action, then decrement `levels`. As long as
            // `levels` is greater then 1, we keep climbing up the three and excecute
            // that superstate exit action.
            if let Some(mut superstate) = self.superstate() {
                while levels > 1 {
                    superstate.call_exit_action(shared_storage, context).await;
                    superstate = match superstate.superstate() {
                        Some(superstate) => superstate,
                        None => break,
                    };
                    levels -= 1;
                }
            }
        }
    }
```

--------------------------------

### Implement Serde deserialization

Source: https://docs.rs/statig/latest/src/statig/awaitable/inner.rs.html

Deserialization support for the Inner struct when the serde feature is enabled.

```rust
#[cfg(feature = "serde")]
/// A serialized state machine can only be deserialized into an [`UnInitializedStateMachine`] and can
/// then be initialized with [`init`](UnInitializedStateMachine::init).
impl<'de, M> serde::Deserialize<'de> for Inner<M>
where
    M: IntoStateMachine + serde::Deserialize<'de>,
    M::State: serde::Deserialize<'de>,
{
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use core::marker::PhantomData;

        enum Field {
            SharedStorage,
            State,
        }

        impl<'de> serde::Deserialize<'de> for Field {
            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
            where
                D: serde::Deserializer<'de>,
            {
                struct FieldVisitor;

                impl<'de> serde::de::Visitor<'de> for FieldVisitor {
                    type Value = Field;

                    fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
                        formatter.write_str("`shared_storage` or `state`")
                    }

                    fn visit_str<E>(self, value: &str) -> Result<Field, E>
                    where
```

--------------------------------

### Access Shared Storage

Source: https://docs.rs/statig/latest/index.html

State machine fields can be accessed within states or actions by taking &mut self.

```rust
#[state]
fn led_on(&mut self, event: &Event) -> Outcome<State> {
    match event {
        Event::TimerElapsed => {
            self.led = false;
            Transition(State::led_off())
        }
        _ => Super
    }
}
```

```rust
#[action]
fn enter_led_off(&mut self) {
    self.led = false;
}
```

--------------------------------

### Implement transition hooks for state machines

Source: https://docs.rs/statig/latest/src/statig/awaitable/into_state_machine.rs.html

TransitionHook provides a mechanism to execute asynchronous logic during state transitions, with support for varying function argument counts.

```rust
pub trait TransitionHook<T, P>
where
    T: IntoStateMachine,
{
    fn call_transition_hook(
        self,
        shared_storage: &mut T,
        source: &T::State,
        target: &T::State,
        context: &mut T::Context<'_>,
    ) -> impl Future<Output = ()>;
}

impl<T, F> TransitionHook<T, ((),)> for F
where
    T: IntoStateMachine,
    F: AsyncFnOnce(&mut T, &T::State, &T::State),
{
    fn call_transition_hook(
        self,
        shared_storage: &mut T,
        source: &T::State,
        target: &T::State,
        _context: &mut T::Context<'_>,
    ) -> impl Future<Output = ()> {
        (self)(shared_storage, source, target)
    }
}

impl<T, F> TransitionHook<T, ((), ())> for F
where
    T: IntoStateMachine,
    F: AsyncFnOnce(&mut T, &T::State, &T::State, &mut T::Context<'_>),
{
    fn call_transition_hook(
        self,
        shared_storage: &mut T,
        source: &T::State,
        target: &T::State,
        context: &mut T::Context<'_>,
    ) -> impl Future<Output = ()> {
        (self)(shared_storage, source, target, context)
    }
}
```

--------------------------------

### Statig Library Module Exports

Source: https://docs.rs/statig/latest/src/statig/lib.rs.html

Public re-exports and module declarations for the Statig crate.

```rust
pub use crate::awaitable::{IntoStateMachineExt as _, StateExt as _, *};
pub use crate::blocking::{IntoStateMachineExt as _, StateExt as _, *};
pub use crate::Outcome::{self, *};
pub use crate::StateOrSuperstate;
#[cfg(feature = "macro")]
#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
pub use statig_macro::state_machine;
}

pub mod blocking;

#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
pub mod awaitable;

pub use outcome::*;
pub use state_or_superstate::*;
```

--------------------------------

### Accessing the underlying state machine type

Source: https://docs.rs/statig/latest/src/statig/awaitable/state_machine.rs.html

Demonstrates how to retrieve a reference to the underlying type of a state machine.

```rust
# use statig::prelude::*;
# #[derive(Default)]
# pub struct Blinky {
#     led: bool,
# }
#
# pub struct Event;
#
# #[state_machine(
#     initial = "State::on()",
#     state(derive(Debug, PartialEq, Eq))
# )]
# impl Blinky {
#     #[state]
#     async fn on(event: &Event) -> Outcome<State> { Handled }
# }
#
let state_machine = Blinky::default().state_machine();
assert_eq!(state_machine.inner().led, false);
```
Tokens:
Raw