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 state *	stateM_currentState (struct stateMachine *stateMachine)
	Get the current state.
struct state *	stateM_previousState (struct stateMachine *stateMachine)
	Get 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, guards and entry/exit routines. All state machine data is stored in separate objects, and the state machine must be built by the user. States are connected using pointers, and all data can be stored on either the stack, heap or both.

---

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.

See Also

state

transition

Examples:

nestedTest.c, and 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 type in order to make it possible to always cast the data correctly.
int	type	Type of event. Defined by user.

struct stateMachine

State machine.

There is no need to manipulate the members directly.

Examples:

nestedTest.c, and stateMachineExample.c.

Class Members
struct state *	currentState	Pointer to the current state.
struct state *	errorState	Pointer to a state that will be entered whenever an error occurs in the state machine. See stateM_errorStateReached for when the state machine enters the error state.
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

enum stateM_handleEventRetVals

stateM_handleEvent() return values

Enumerator:

stateM_errArg	Erroneous arguments were passed.
stateM_errorStateReached	The error state was reached. This value is returned either when the state machine enters the error state itself as a result of an error, or when the error state is the next state as a result of a successful transition. The state machine enters the state machine if any of the following happens: 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. The state can return to itself either directly or indirectly. An indirect path may inlude a transition from a parent state and the use of entryStates.
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

Get the current state.

Parameters

stateMachine

the state machine to get the current state from.

Return values

a	pointer to the current state.
NULL	if 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 transition has an action defined, it will be called. If the transition is to a state other than the current state, the current state's exit action is called (if defined). Likewise, if the state is a new state, the new state's entry action is called (if defined).

The returned value is negative if an error occurs.

Parameters

stateMachine	the state machine to pass an event to.
event	the event to be handled.

Returns

stateM_handleEventRetVals

Examples:

nestedTest.c, and 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.

If initialState is a parent state with its entryState defined, it will not be entered. The user must explicitly set the initial state.

Parameters

stateMachine	the state machine to initialise.
initialState	the initial state of the state machine.
errorState	pointer to a state that acts a final state and notifies the system/user that an error has occurred.

Examples:

nestedTest.c, and stateMachineExample.c.

struct state* stateM_previousState ( struct stateMachine *  stateMachine )

read

Get the previous state.

Parameters

stateMachine

the state machine to get the previous state from.

Return values

the	previous state.
NULL	if stateMachine is NULL.
NULL	if there has not yet been any transitions.

bool stateM_stopped

(

struct stateMachine *

stateMachine

)

Check if the state machine has stopped.

Parameters

stateMachine

the state machine to test.

Return values

true	if the state machine has reached a final state.
false	if stateMachine is NULL or if the current state is not a final state.