Crate macro_machines

State machine macros with logging and graphviz dotfile 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 (wth associated action) and Close (without any action)
• an open_count extended state variable -- 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 dotfile string that can be saved and rendered as a PNG with graphviz dot layout:

$ dot -Tpng door.dot > door.png

Macros

debug	Logs a message at the debug level.
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.
error	Logs a message at the error level.
info	Logs a message at the info level.
log	The standard logging macro.
trace	Logs a message at the trace level.
warn	Logs a message at the warn level.

Enums

HandleEventException

Describes an exceptional result when attempting to handle an event.

Traits

MachineDotfile

Methods for dotfile creation