Crate finny

source · []
Expand description

Finny - Hierarchical Finite State Machines for Rust Documentation Build


  • Declarative, builder API with a procedural function macro that generate the dispatcher
  • Compile-time transition graph validation
  • No run-time allocations required, no_std support
  • Support for generics within the shared context
  • Transition guards and actions
  • State regions, also known as orthogonal states
  • Event queueing and run-to-completition execution
  • Submachines, also known as Hierarchical State Machines
  • Timers on states



finny = "0.2"


use finny::{finny_fsm, FsmFactory, FsmResult, decl::{BuiltFsm, FsmBuilder}};
// The context is shared between all guards, actions and transitions. Generics are supported here!
pub struct MyContext { val: u32 }
// The states are plain structs.
pub struct MyStateA { n: usize }
pub struct MyStateB;
// The events are also plain structs. They can have fields.
pub struct MyEvent;

// The FSM is generated by a procedural macro
fn my_fsm(mut fsm: FsmBuilder<MyFsm, MyContext>) -> BuiltFsm {
    // The FSM is described using a builder-style API
       .on_entry(|state, ctx| {
           state.n += 1;
           ctx.context.val += 1;
       .guard(|_ev, ctx, _states| { ctx.context.val > 0 })
       .action(|_ev, ctx, state_a, state_b| { ctx.context.val += 1; });
// The FSM is built and tested.
fn main() -> FsmResult<()> {
    let mut fsm = MyFsm::new(MyContext::default())?;
    assert_eq!(0, fsm.val);
    let state_a: &MyStateA = fsm.get_state();
    assert_eq!(1, state_a.n);
    assert_eq!(1, fsm.val);
    assert_eq!(2, fsm.val);


External bundled libraries to be used by the procedural macros.

The builder-style API structures for defining your Finny FSM. The procedural macro parses these method calls and generated the optimized implementation.

A heapless queue with Clone and Arc support.


The context that is given to all of the guards and actions.

The struct that holds the core context and state of the given Finny FSM. Doesn’t include environmental traits that can be changed at runtime.

A heapless queue with a fixed size. Implemented using the arraydequeue crate.

An unbound event queue that uses VecDeque.

An unbound event queue that uses VecDeque.

The frontend of a state machine which also includes environmental services like queues and inspection. The usual way to use the FSM.


The current state of the FSM.

The lib-level error type.

The internal event type that also allows stopping or starting the machine.


Enumerates all the possible variants of a simple enum.

An internal or self action can only mutate itself.

Finite State Machine backend. Handles the dispatching, the types are defined by the code generator.

The event queueing trait for FSMs. Can be used from outside or from within the actions of the FSM.

Builds a frontend for running your FSM.

A state’s entry and exit actions.

Create a new state from the shared global context.

Retrieve a pair of states as mutable references. Used in state transitions.

Retrieve a pair of states as immutable references. Used in state transitions.

The implementation should hold all of the FSM’s states as fields.

A transition’s action that operates on both the exit and entry states.

The transition that starts the machine, triggered using the start() method.

Check if this transition is allowed to be entered.

Associate some data with a specific timer ID.


Used to funnel the event down to the sub-machine.

Type Definitions

Attribute Macros

The procedural macro that will transform the builder function into the FSM.