Out-of-office display, GFX
 All Classes Files Functions Variables Enumerations Enumerator Groups
Files | Classes | Enumerations | Functions
State machine

Finite state machine. More...

Files

file  stateMachine.h

Classes

struct  event
 Event. More...
struct  transition
 Transition between a state and another state. More...
struct  state
 State. More...
struct  stateMachine
 State machine. More...

Enumerations

enum  stateM_handleEventRetVals {
  stateM_errArg = -2, stateM_errorStateReached, stateM_stateChanged, stateM_stateLoopSelf,
  stateM_noStateChange, stateM_finalStateReached
}
 stateM_handleEvent() return values More...

Functions

void stateM_init (struct stateMachine *stateMachine, struct state *initialState, struct state *errorState)
 Initialise the state machine.
int stateM_handleEvent (struct stateMachine *stateMachine, struct event *event)
 Pass an event to the state machine.
struct statestateM_currentState (struct stateMachine *stateMachine)
 The current state.
struct statestateM_previousState (struct stateMachine *stateMachine)
 The previous state.
bool stateM_stopped (struct stateMachine *stateMachine)
 Check if the state machine has stopped.

Detailed Description

Finite state machine.

Author
Andreas Misje
Date
27.03.13

A finite state machine implementation that supports nested states, guard conditions and entry/exit routines. No static variables are used, making it possible to run numerous instances of the state machine. No heap allocation is performed; all data is given as pointers to the module and can be stored either on the stack or the heap.


Class Documentation

struct event

Event.

Events trigger transitions from a state to another. Event types are defined by the user. Any event may optionally contain a payload (data).

See Also
state
transition
Examples:
stateMachineExample.c.
Class Members
void * data Event payload. How this is used is entirely up to the user. This data is always passed together with an eventType in order to make it possible to always cast the data correctly.
int type Type of event. Defined by user.
struct stateMachine

State machine.

Should not be manipulated directly by user.

Examples:
stateMachineExample.c.
Class Members
struct state * currentState Pointer to the current state.
struct state * errorState Pointer to the state which will be entered whenever an error occurs in the state machine.
struct state * previousState Pointer to previous state. The previous state is stored for convenience in case the user needs to keep track of previous states.

Enumeration Type Documentation

stateM_handleEvent() return values

Enumerator:
stateM_errArg 

Erroneous arguments were passed.

stateM_errorStateReached 

The error state was reached.

The state machine enters the state machine if any of the following happends:

  • The current state is NULL
  • A transition for the current event did not define the next state
stateM_stateChanged 

The current state changed into a non-final state.

stateM_stateLoopSelf 

The state changed back to itself.

stateM_noStateChange 

The current state did not change on the given event.

If any event passed to the state machine should result in a state change, this return value should be considered as an error.

stateM_finalStateReached 

A final state (any but the error state) was reached.

Function Documentation

struct state* stateM_currentState ( struct stateMachine stateMachine)
read

The current state.

Parameters
stateMachinethe state machine to get the current state from.
Return values
apointer to the current state.
NULLif stateMachine is NULL.
int stateM_handleEvent ( struct stateMachine stateMachine,
struct event event 
)

Pass an event to the state machine.

The event will be passed to the current state, and possibly to the current state's parent states (if any). If the event triggers a transition, a new state will be entered. If the new state has an entryAction defined, it will be called.

Parameters
stateMachinethe state machine to pass an event to.
eventthe event to be handled.
Returns
stateM_handleEventRetVals
Examples:
stateMachineExample.c.
void stateM_init ( struct stateMachine stateMachine,
struct state initialState,
struct state errorState 
)

Initialise the state machine.

This function initialises the supplied stateMachine and sets the current state to initialState. No actions are performed until stateM_handleEvent() is called. It is safe to call this function numerous times, for instance in order to reset/restart the state machine if a final state has been reached.

Note
The entry action for initialState will not be called.
Parameters
stateMachinethe state machine to initalise.
initialStatethe initial state of the state machine.
errorStatepointer to a state that acts a final state and notifys the system/user that an eror has occurred.
Examples:
stateMachineExample.c.
struct state* stateM_previousState ( struct stateMachine stateMachine)
read

The previous state.

Parameters
stateMachinethe state machine to get the previous state from.
Return values
theprevious state.
NULLif stateMachine is NULL.
NULLif there has not yet been any transitions.
bool stateM_stopped ( struct stateMachine stateMachine)

Check if the state machine has stopped.

Parameters
stateMachinethe state machine to test.
Return values
trueif the state machine has reached a final state.
falseif stateMachine is NULL or if the current state is not a final state.