#state-machine #finite-state-machine #state #fsm

no-std finny

Finite State Machines with a procedural builder-style API and compile time transition checks

3 unstable releases

0.2.0 Jan 24, 2022
0.1.1 Jan 5, 2021
0.1.0 Jan 5, 2021

#1043 in Algorithms

30 downloads per month

MIT/Apache

93KB
2K SLoC

Finny - Hierarchical Finite State Machines for Rust

Crates.io Documentation Build

Features

  • 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

Example

Cargo.toml

[dependencies]
finny = "0.2"

Code

use finny::{finny_fsm, FsmFactory, FsmResult, decl::{BuiltFsm, FsmBuilder}};

// The context is shared between all guards, actions and transitions. Generics are supported here!
#[derive(Default)]
pub struct MyContext { val: u32 }
// The states are plain structs.
#[derive(Default)]
pub struct MyStateA { n: usize }
#[derive(Default)]
pub struct MyStateB;
// The events are also plain structs. They can have fields.
#[derive(Clone)]
pub struct MyEvent;

// The FSM is generated by a procedural macro
#[finny_fsm]
fn my_fsm(mut fsm: FsmBuilder<MyFsm, MyContext>) -> BuiltFsm {
    // The FSM is described using a builder-style API
    fsm.state::<MyStateA>()
       .on_entry(|state, ctx| {
           state.n += 1;
           ctx.context.val += 1;
        })
       .on_event::<MyEvent>()
       .transition_to::<MyStateB>()
       .guard(|_ev, ctx, _states| { ctx.context.val > 0 })
       .action(|_ev, ctx, state_a, state_b| { ctx.context.val += 1; });
    fsm.state::<MyStateB>();
    fsm.initial_state::<MyStateA>();
    fsm.build()
}

// The FSM is built and tested.
fn main() -> FsmResult<()> {
    let mut fsm = MyFsm::new(MyContext::default())?;
    assert_eq!(0, fsm.val);
    fsm.start()?;
    let state_a: &MyStateA = fsm.get_state();
    assert_eq!(1, state_a.n);
    assert_eq!(1, fsm.val);
    fsm.dispatch(MyEvent)?;
    assert_eq!(2, fsm.val);
    Ok(())
}

License: MIT OR Apache-2.0

Dependencies

~4.5MB
~95K SLoC