The transition_map manages state machines and causes state changes to occur. More...
#include <state_machine.h>
Public Types | |
| enum | outcomes { OKAY = basis::common::OKAY , DEFINE_OUTCOME , DEFINE_OUTCOME } |
Public Member Functions | |
| transition_map () | |
| virtual | ~transition_map () |
| DEFINE_CLASS_NAME ("transition_map") | |
| bool | valid () const |
| returns true if the transition_map is valid and ready for operation. More... | |
| int | states () const |
| returns the current number of states. More... | |
| basis::outcome | validate (int &examine) |
| checks to that all required transition conditions are satisfied. More... | |
| void | reconfigure () |
| puts the transition_map back into an unvalidated state. More... | |
| bool | add_state (int state_number) |
| registers a legal state in the transition_map. More... | |
| bool | set_start (int starting_state) |
| assigns a state as the first state. More... | |
| bool | add_simple_transition (int current, int next) |
| adds a transition between "current" and "next". More... | |
| bool | add_range_transition (int current, int next, int low, int high) |
| adds a transition that listens to triggers in the pulse() method. More... | |
| bool | add_timed_transition (int current, int next, int duration) |
| adds a transition that occurs after a timeout with no other activity. More... | |
| bool | make_transition (state_machine &m, int next) |
| changes the state to the "next" listed for "m" given the current state. More... | |
| bool | pulse (state_machine &m, int trigger) |
| applies a "trigger" to possibly cause a range transition. More... | |
| bool | time_slice (state_machine &m) |
| bool | reset (state_machine &m) |
Detailed Description
The transition_map manages state machines and causes state changes to occur.
The transition_map is a heavyweight class that is a repository for all information about transitions and which manages pushing the state machines through the proper states.
The transition_map guarantees these characteristics:
0) the below characteristics are checked (in validate) and no state machine object is allowed to operate until they are satisfied,
1) the machine starts in the specified starting state,
2) the current state is always one that has been added and approved,
3) transitions are allowed between states only if the transition has been added and approved,
4) the update() function is invoked every time the machine hits a transition between states (even if it is a transition to the same state),
5) range transitions are non-intersecting within one state, 5 is unimplemented ***
6) all states are reachable from the starting state by some valid transition, and
7) each state has no more than one timed transition.
if any of these conditions are violated, then validate() will fail. the machine will also not operate properly (at all) until the conditions are satisfied by validate(). the states and transitions should thus be carefully examined before turning them into a state machine....
Definition at line 190 of file state_machine.h.
Member Enumeration Documentation
◆ outcomes
| Enumerator | |
|---|---|
| OKAY | |
| DEFINE_OUTCOME | |
| DEFINE_OUTCOME | |
Definition at line 210 of file state_machine.h.
Constructor & Destructor Documentation
◆ transition_map()
| processes::transition_map::transition_map | ( | ) |
Definition at line 223 of file state_machine.cpp.
◆ ~transition_map()
|
virtual |
Definition at line 229 of file state_machine.cpp.
References basis::WHACK().
Member Function Documentation
◆ add_range_transition()
| bool processes::transition_map::add_range_transition | ( | int | current, |
| int | next, | ||
| int | low, | ||
| int | high | ||
| ) |
adds a transition that listens to triggers in the pulse() method.
this uses "low" and "high" as the inclusive range of triggers that will cause a transition to the "next" state when a state_machine is pulsed in the "current" state. it is erroneous for these trigger values to intersect with other values in the same "current" state.
Definition at line 306 of file state_machine.cpp.
References CHECK_STATES, and valid().
◆ add_simple_transition()
| bool processes::transition_map::add_simple_transition | ( | int | current, |
| int | next | ||
| ) |
adds a transition between "current" and "next".
it is an error to use either an invalid "current" state or an invalid "next" state. these errors are detected during the validate() function. this type of transition is unspecialized–it does not respond to triggers and does not occur due to timing. to make a state_machine undergo this transition, make_transition() must be used.
Definition at line 298 of file state_machine.cpp.
References CHECK_STATES, and valid().
◆ add_state()
| bool processes::transition_map::add_state | ( | int | state_number | ) |
registers a legal state in the transition_map.
no action will be taken for any state until it is registered. the operation returns true for successful registration and false for errors (such as when a state is already registered or is invalid).
Definition at line 278 of file state_machine.cpp.
References basis::non_negative(), and valid().
◆ add_timed_transition()
| bool processes::transition_map::add_timed_transition | ( | int | current, |
| int | next, | ||
| int | duration | ||
| ) |
adds a transition that occurs after a timeout with no other activity.
adds a timed transition to the "next" state when the "current" state has lasted "duration" milliseconds. this relies on the time_slice function being called periodically, with appropriate regularity for the specified "duration" (e.g., if one's time-out is 100 ms, then one might want to call time_slice() every 20 ms or so to ensure that the transition is at most 20 ms late in firing. NOTE: this is not an argument for calling time_slice() as fast as possible; it is an argument for realizing that the "duration" must be carefully considered to meet one's timing deadlines).
Definition at line 314 of file state_machine.cpp.
References CHECK_STATES, and valid().
◆ DEFINE_CLASS_NAME()
| processes::transition_map::DEFINE_CLASS_NAME | ( | "transition_map" | ) |
◆ make_transition()
| bool processes::transition_map::make_transition | ( | state_machine & | m, |
| int | next | ||
| ) |
changes the state to the "next" listed for "m" given the current state.
it is an error to make a transition that has not been specified through an add_X() transition function (false is returned). if the transition succeeds, then the current_state will be "next".
Definition at line 332 of file state_machine.cpp.
References CHECK_VALID, FIND_STATE, LOG, MOVE_STATE, basis::negative(), pulse(), basis::astring::s(), processes::state_machine::SIMPLE, processes::state_machine::update(), and valid().
◆ pulse()
| bool processes::transition_map::pulse | ( | state_machine & | m, |
| int | trigger | ||
| ) |
applies a "trigger" to possibly cause a range transition.
this causes the state_machine to accept the "trigger" as input and perform at least one traversal of the transition_map. if the trigger value is found in one of the range transitions for the current state, then the next state specified in that transition becomes the current state and the update() function is invoked (and true is returned). if the trigger is not found in any range transition, then false is returned.
Definition at line 354 of file state_machine.cpp.
References CHECK_VALID, FIND_STATE, LOG, MOVE_STATE, basis::negative(), processes::state_machine::RANGE, basis::astring::s(), processes::state_machine::update(), and valid().
Referenced by make_transition(), and time_slice().
◆ reconfigure()
| void processes::transition_map::reconfigure | ( | ) |
puts the transition_map back into an unvalidated state.
this allows the characteristics of the map to be changed. validate() must be called again before resuming operation using this map.
Definition at line 262 of file state_machine.cpp.
◆ reset()
| bool processes::transition_map::reset | ( | state_machine & | m | ) |
Definition at line 413 of file state_machine.cpp.
References timely::time_stamp::reset(), processes::state_machine::SIMPLE, and valid().
◆ set_start()
| bool processes::transition_map::set_start | ( | int | starting_state | ) |
assigns a state as the first state.
if the "starting_state" does not already exist, it is an error and false is returned.
Definition at line 287 of file state_machine.cpp.
References FIND_STATE, and valid().
◆ states()
| int processes::transition_map::states | ( | ) | const |
returns the current number of states.
Definition at line 237 of file state_machine.cpp.
◆ time_slice()
| bool processes::transition_map::time_slice | ( | state_machine & | m | ) |
Definition at line 381 of file state_machine.cpp.
References CHECK_VALID, processes::state_machine::duration_override(), FIND_STATE, LOG, MOVE_STATE, basis::negative(), pulse(), basis::astring::s(), processes::state_machine::TIMED, processes::state_machine::update(), and valid().
◆ valid()
|
inline |
returns true if the transition_map is valid and ready for operation.
once the validate() call has succeeded and valid() is true, no more configuration functions (see below) may be called until the reconfigure() function is invoked.
Definition at line 200 of file state_machine.h.
Referenced by add_range_transition(), add_simple_transition(), add_state(), add_timed_transition(), make_transition(), pulse(), reset(), set_start(), and time_slice().
◆ validate()
| outcome processes::transition_map::validate | ( | int & | examine | ) |
checks to that all required transition conditions are satisfied.
OKAY is returned if they are and the map is then ready to operate. other outcomes are returned if one or more of the conditions are not met: BAD_START means that the starting state is badly specified. OVERLAPPING_RANGES means that one state has two transitions that do not have mutually exclusive ranges. UNREACHABLE means that a state is not reachable from the starting state. for all of these cases, the "examine" parameter is set to a state related to the problem.
Definition at line 264 of file state_machine.cpp.
References FIND_STATE, and OKAY.
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
