Crate statement

This library provides an Event-Driven State Machine implementation for Rust

A State Machine describes a struct that maintains a State variable in a predictable way, using a set of Transitions to describe how the state may change. Transitions are triggered by Events, which are generated by the environment, and may in turn cause Effects to execute, which can influence the environment. State Machines may also carry arbitrary Data, which can be mutated by Effects.

In this State Machine implementation, the State Machine is operated by providing it with Events through the StateMachine::handle_event method. Events can be anything, but it is common to represent them with an Enum.

States themselves are very restricted to allow for Any / AllOf matching, and typically should also be implemented with an enum that derives Copy, Clone, Eq, PartialEq, and Debug.

Defining Transitions

State Machines in statement are simply a thin wrapper over a state object and a list of transitions. To define a state machine, you need to:

1. Create a StateMachineFactory using StateMachineFactory::new
2. Add transitions using one or more of:
   • StateMachineFactory::with_predicated_transition
   • StateMachineFactory::with_predicated_transition_effect
   • StateMachineFactory::with_event_transition
   • StateMachineFactory::with_event_transition_effect
   • StateMachineFactory::with_auto_transition
   • StateMachineFactory::with_custom_transition
3. Lock your factory into a LockedStateMachineFactory by calling StateMachineFactory::lock
4. Create a state machine by calling LockedStateMachineFactory::build

Transitions

Transitions (represented by the StateMachineTransition struct) must specify the State or set of initial states (as a FromState) that may trigger them:

• FromState::Any: Any starting state - this Transition will be evaluated for all events.
• FromState::AnyOf: Any starting state in the provided list.
• FromState::From: The specific provided started state. FromState implements From for this variant, so the variant can be elided for the common case.

Transitions may also optionally provide a predicate to apply custom logic to decide whether the Transition is applied. Transitions may also be triggered from any (FromState::Any) state, meaning that they are considered for any Event.

Transitions must also describe the state that they transition the State Machine into. The to_state of a transition can be represented as one of the following:

• To: A specific, pre-defined state. ToState implements From for this variant, so the variant can be elided for the common case.
• Same: Whatever state the transition started from; this makes the transition a no-op for the state machine, but side effects may still be executed. This is useful in some cases, such as in transition loggers.
• Calc: Allows for dynamic target state calculation, when a given transition may result in more than one target states. This is something of an antipattern; these should preferentially be represented as multiple transitions with different predicates.

Event Lifecycle

1. Handle event called.

2. For each defined transition:

   2a. Determine if the from_state of the transition matches the current state. If false, break and move on to the next transition.

   2b. Determine the to_state of the transition.

   2c. Run the transition’s predicate, if any. If false (or no predicate), break and move on to the next transition.

   2d. Run the transition’s effect, if any.

   2e. Transition the state machine to the to_state determined in 2b above.

3. If the State Machine has cycle set to true, return to 2.

Structs

LockedStateMachineFactory

Locked Factory for StateMachines. This struct is created by calling .lock() on a StateMachineFactory, usually after defining all transitions needed.

StateMachine

State Machine instance, usually created by calling create on a LockedStateMachineFactory

StateMachineFactory

Factory for StateMachines. This struct can be used to define a series of Transitions that may be subsequently used to create multiple state machine instances with those same transitions.

StateMachineTransition

Describes a Transition between States, potentially with a Predicate and/or Effect

StateTransitionEffectData

Data passed to a Transition Effect callback.

StateTransitionToStateData

Data passed to a Transition ToState callback.

Enums

FromState

Indicates the State or set of States from which a Transition is valid

StateMachineError

Basic error type for StateMachine

ToState

Indicates how a result State is determined after transitioning