Crate macro_machines

State machine macros with logging and graphviz DOT file generation.

Repository

An example that shows a number of features of the macro syntax is a Door state machine with:

• two states: Closed (with state-local variable knock_count) and Open
• three events: one internal event Knock (with action on the Closed state) and two external events Open (with associated action) and Close (without any action)
• an extended state variable open_count -- this variable is initialized once and is independent of the current machine state

def_machine_debug! {
  Door (open_count : u64) @ door {
    STATES [
      state Closed (knock_count : u64)
      state Opened ()
    ]
    EVENTS [
      event Knock <Closed> () { knock_count } => { *knock_count += 1; }
      event Open  <Closed> => <Opened> ()  {} => { *open_count += 1; }
      event Close <Opened> => <Closed> ()
    ]
    initial_state:  Closed {
      initial_action: {
        println!("hello");
        println!("open_count: {:?}", door.as_ref().open_count);
      }
    }
    terminal_state: Closed {
      terminate_success: {
        println!("open_count: {:?}", door.as_ref().open_count);
        println!("goodbye")
      }
      terminate_failure: {
        panic!("door was left: {:?}", door.state())
      }
    }
  }
}

To optionally make the state machine accessible in initial and terminal action blocks, the macro implementation requires an identifier door be introduced here following the @ symbol. The variable is then brought into scope as an alias for a mutable self-reference in initial and terminal action blocks.

In event actions, mutable references to extended state variables will implicitly be brought into scope of the associated action block, however local state variables need to be explicitly listed in the LHS brace of the action construct to be accessible (e.g. the knock_count local state variable in the Knock event action of the current example).

The Door::dotfile() function will generate a '.dot' file string that can be saved and rendered as a PNG with layout generated by graphviz dot tool:

$ dot -Tpng door.dot > door.png

Macros

def_machine	State machines with a default initial state.
def_machine_debug	State machines with a default initial state and deriving Debug.
def_machine_nodefault	State machine that requires runtime initialization.
def_machine_nodefault_debug	State machine that requires runtime initialization and deriving Debug.

Enums

HandleEventException

Describes an exceptional result when attempting to handle an event.

Traits

MachineDotfile

Methods for DOT file creation