Monitors objects with multiple states and the transitions between states. More...
#include <state_machine.h>
Public Types | |
| enum | transition_types { SIMPLE , RANGE , TIMED } |
Public Member Functions | |
| state_machine () | |
| sets up the machine in a blank state. More... | |
| state_machine (const state_machine &to_copy) | |
| copies the machine provided in "to_copy". More... | |
| virtual | ~state_machine () |
| DEFINE_CLASS_NAME ("state_machine") | |
| state_machine & | operator= (const state_machine &to_copy) |
| assigns this to a copy of the machine provided in "to_copy". More... | |
| virtual int | update () |
| this is the main implementation function provided by derived classes. More... | |
| int | current () const |
| returns the current state. More... | |
| int | last () const |
| returns the last active state. More... | |
| int | trigger () const |
| returns the trigger that caused this state. More... | |
| bool | simple () const |
| returns true if the last transition was a simple type. More... | |
| bool | ranged () const |
| returns true if the last transition was a ranged type. More... | |
| bool | timed () const |
| returns true if the last transition was a timed type. More... | |
| void | set_state (int new_current, int new_last, int trigger, transition_types type) |
| sets the current state to "new_current" and the previous state to "new_last". More... | |
| timely::time_stamp | start () const |
| start time for the current state. More... | |
| void | set_name (const basis::astring &name) |
| sets the name to be printed in any debugging information for "this". More... | |
| basis::astring | get_name () const |
| retrieves the object's current name. More... | |
| void | override_timing (int current, int next, int duration) |
| modifies the recorded timing for timed transitions. More... | |
| int | duration_override (int current, int next) const |
| reports if there's a duration override for a timed transition. More... | |
Friends | |
| class | transition_map |
| manager buddy object. More... | |
Detailed Description
Monitors objects with multiple states and the transitions between states.
A state machine is a computational abstraction for any control process that has discrete states and transitions between the states. As used here, the "state_machine" is a base class for objects that can be manipulated by the "transition_map" class. Your transition map must be validated and you must use it to reset() your state_machine object before any activity can occur. (One aspect of validation is that all states must be reachable from the user-specified starting state. The other requirements are documented below for transition_map.) Once validation is done, the transition map manages the machine through the various states that are defined and applies trigger values to modify the current state when asked to do so. It also applies any defined timed transitions automatically. This implementation of state machines is configured once (by defining the transition_map object), but then the machines can be run repeatedly (via the state_machine object).
Definition at line 44 of file state_machine.h.
Member Enumeration Documentation
◆ transition_types
| Enumerator | |
|---|---|
| SIMPLE | |
| RANGE | |
| TIMED | |
Definition at line 89 of file state_machine.h.
Constructor & Destructor Documentation
◆ state_machine() [1/2]
| processes::state_machine::state_machine | ( | ) |
sets up the machine in a blank state.
Definition at line 127 of file state_machine.cpp.
◆ state_machine() [2/2]
| processes::state_machine::state_machine | ( | const state_machine & | to_copy | ) |
copies the machine provided in "to_copy".
Definition at line 137 of file state_machine.cpp.
◆ ~state_machine()
|
virtual |
Definition at line 148 of file state_machine.cpp.
References basis::WHACK().
Member Function Documentation
◆ current()
|
inline |
returns the current state.
NOTE: a zero value for a state means that it is uninitialized.
Definition at line 79 of file state_machine.h.
Referenced by duration_override(), and override_timing().
◆ DEFINE_CLASS_NAME()
| processes::state_machine::DEFINE_CLASS_NAME | ( | "state_machine" | ) |
◆ duration_override()
| int processes::state_machine::duration_override | ( | int | current, |
| int | next | ||
| ) | const |
reports if there's a duration override for a timed transition.
this returns the amount of time that this particular state_machine is allowed to exist in the "current" state before progressing to the "next" state. this has nothing to do with the transition_map; it is valid only for this state_machine object. zero is returned if no override exists.
Definition at line 212 of file state_machine.cpp.
References current(), and basis::negative().
Referenced by processes::transition_map::time_slice().
◆ get_name()
| astring processes::state_machine::get_name | ( | ) | const |
retrieves the object's current name.
Definition at line 159 of file state_machine.cpp.
◆ last()
|
inline |
returns the last active state.
Definition at line 82 of file state_machine.h.
◆ operator=()
| state_machine & processes::state_machine::operator= | ( | const state_machine & | to_copy | ) |
assigns this to a copy of the machine provided in "to_copy".
Definition at line 161 of file state_machine.cpp.
◆ override_timing()
| void processes::state_machine::override_timing | ( | int | current, |
| int | next, | ||
| int | duration | ||
| ) |
modifies the recorded timing for timed transitions.
this overrides the transition_map's time-out value for the transition between the states "current" and "next". a time-out of "duration" will be used instead of whatever was specified when the map was set up. to erase an override, use zero as the "duration".
Definition at line 194 of file state_machine.cpp.
References current(), and basis::non_negative().
◆ ranged()
|
inline |
returns true if the last transition was a ranged type.
Definition at line 94 of file state_machine.h.
References SIMPLE.
◆ set_name()
| void processes::state_machine::set_name | ( | const basis::astring & | name | ) |
sets the name to be printed in any debugging information for "this".
Definition at line 157 of file state_machine.cpp.
◆ set_state()
| void processes::state_machine::set_state | ( | int | new_current, |
| int | new_last, | ||
| int | trigger, | ||
| transition_types | type | ||
| ) |
sets the current state to "new_current" and the previous state to "new_last".
the "trigger" causing the transition, if any, will be stored also. the "type" of transition is stored also. the time stamp for time spent in the current state is reset. be very careful with this; if the two states do not conform to the legal transitions in your map, then the state machine will not behave properly.
Definition at line 184 of file state_machine.cpp.
References timely::time_stamp::reset(), and trigger().
◆ simple()
|
inline |
returns true if the last transition was a simple type.
Definition at line 92 of file state_machine.h.
◆ start()
| time_stamp processes::state_machine::start | ( | ) | const |
start time for the current state.
this records how long we've been in this state.
Definition at line 219 of file state_machine.cpp.
◆ timed()
|
inline |
returns true if the last transition was a timed type.
Definition at line 96 of file state_machine.h.
References RANGE.
◆ trigger()
|
inline |
returns the trigger that caused this state.
this is only meaningful when the transition was caused by a range transition. if it was, then ranged() will return true.
Definition at line 85 of file state_machine.h.
Referenced by set_state().
◆ update()
|
virtual |
this is the main implementation function provided by derived classes.
this is implemented by derived classes that want to perform an action when the state machine is pulsed (see below in transition_map), which is why it is not pure virtual; a state machine might still be useful as a state tracking object rather than needing to implement extended functionality. this function is invoked whenever the state changes due to a timed, range based or simple transition. one must be careful when servicing this transition not to enmesh oneself in a snarled invocation situation; if make_transition or time_slice or pulse are invoked from this update function and conditions are right for another transition, then the update function will be re-entered recursively. if the value returned from update is non-zero, it is used to pulse the state machine again as a new trigger value (this is safer than explicitly calling one of the transition causing functions). note that this assumes that zero is an invalid trigger. if your triggers include zero as a valid value, don't try returning it through update; use pulse to force the triggering to accept the invalid trigger instead.
Definition at line 155 of file state_machine.cpp.
Referenced by processes::transition_map::make_transition(), processes::transition_map::pulse(), and processes::transition_map::time_slice().
Friends And Related Function Documentation
◆ transition_map
|
friend |
manager buddy object.
Definition at line 133 of file state_machine.h.
The documentation for this class was generated from the following files:
- /opt/feistymeow.org/feisty_meow/nucleus/library/processes/state_machine.h
- /opt/feistymeow.org/feisty_meow/nucleus/library/processes/state_machine.cpp
