Crate finny

Finny - Hierarchical Finite State Machines for Rust

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(())
}

Modules

• bundled
  External bundled libraries to be used by the procedural macros.
• decl
  The builder-style API structures for defining your Finny FSM. The procedural macro parses these method calls and generated the optimized implementation.
• heapless_shared
  A heapless queue with Clone and Arc support.
• inspect
• timers

Structs

• DispatchContext
• EventContext
  The context that is given to all of the guards and actions.
• FsmBackendImpl
  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.
• FsmEventQueueArray
  A heapless queue with a fixed size. Implemented using the arraydequeue crate.
• FsmEventQueueNull
• FsmEventQueueSub
• FsmEventQueueVec
  An unbound event queue that uses VecDeque.
• FsmEventQueueVecShared
  An unbound event queue that uses VecDeque.
• FsmFrontend
  The frontend of a state machine which also includes environmental services like queues and inspection. The usual way to use the FSM.
• FsmTimersNull
• FsmTimersSub
• FsmTimersTriggerEventsResult
• TimerFsmSettings
• TimerInstance
• TimerSettings

Enums

• FsmCurrentState
  The current state of the FSM.
• FsmError
  The lib-level error type.
• FsmEvent
  The internal event type that also allows stopping or starting the machine.
• InspectFsmEvent

Traits

• AllVariants
  Enumerates all the possible variants of a simple enum.
• FsmAction
  An internal or self action can only mutate itself.
• FsmBackend
  Finite State Machine backend. Handles the dispatching, the types are defined by the code generator.
• FsmBackendResetSubmachine
• FsmEventQueue
  The event queueing trait for FSMs. Can be used from outside or from within the actions of the FSM.
• FsmEventQueueSender
• FsmFactory
  Builds a frontend for running your FSM.
• FsmState
  A state’s entry and exit actions.
• FsmStateFactory
  Create a new state from the shared global context.
• FsmStateTransitionAsMut
  Retrieve a pair of states as mutable references. Used in state transitions.
• FsmStateTransitionAsRef
  Retrieve a pair of states as immutable references. Used in state transitions.
• FsmStates
  The implementation should hold all of the FSM’s states as fields.
• FsmTimer
• FsmTimers
• FsmTransitionAction
  A transition’s action that operates on both the exit and entry states.
• FsmTransitionFsmStart
  The transition that starts the machine, triggered using the start() method.
• FsmTransitionGuard
  Check if this transition is allowed to be entered.
• Inspect
• InspectEvent
• TimersStorage
  Associate some data with a specific timer ID.

Functions

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

Type Aliases

• FsmDispatchResult
• FsmRegionId
• FsmResult

Attribute Macros

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