State. More...

#include <stateMachine.h>

Public Attributes
struct state *	parentState
	If the state has a parent state, this pointer must be non-NULL.
struct state *	entryState
	If this state is a parent state, this pointer may point to a child state that serves as an entry point.
struct transition *	transitions
	An array of transitions for the state.
size_t	numTransitions
	Number of transitions in the transitions array.
void *	data
	Data that will be available for the state in its entryAction and exitAction, and in any transition action.
void(*	entryAction )(void stateData, struct event event)
	This function is called whenever the state is being entered. May be NULL.
void(*	exitAction )(void stateData, struct event event)
	This function is called whenever the state is being left. May be NULL.

Detailed Description

State.

The current state in a state machine moves to a new state when one of the transitions in the current state triggers on an event. An optional exit action is called when the state is left, and an entry action is called when the state machine enters a new state. If a state returns to itself, neither exitAction nor entryAction will be called. An optional transition action is called in either case.

States may be organised in a hierarchy by setting parent states. When a group/parent state is entered, the state machine is redirected to the group state's entry state (if non-NULL). If an event does not trigger a transition in a state and if the state has a parent state, the event will be passed to the parent state. This behaviour is repeated for all parents. Thus all children of a state have a set of common transitions. A parent state's entryAction will not be called if an event is passed on to a child state.

The following lists the different types of states that may be created, and how to create them:

Normal state

struct state normalState = {
   .parentState = &groupState,
   .entryState = NULL,
   .transition = (struct transition[]){
      { Event_keyboard, (void *)(intptr_t)'\n', &compareKeyboardChar,
         NULL, &msgReceivedState },
   },
   .numTransitions = 1,
   .data = normalStateData,
   .entryAction = &doSomething,
   .exitAction = &cleanUp,
};

In this example, normalState is a child of groupState, but the parentState value may also be NULL to indicate that it is not a child of any group state.

Group/parent state

A state becomes a group/parent state when it is linked to by child states by using parentState. No members in the group state need to be set in a particular way. A parent state may also have a parent.

struct state groupState = {
   .entryState = &normalState,
   .entryAction = NULL,

If there are any transitions in the state machine that lead to a group state, it makes sense to define an entry state in the group. This can be done by using entryState, but it is not mandatory. If the entryState state has children, the chain of children will be traversed until a child with its entryState set to NULL is found.

Note: If entryState is defined for a group state, the group state's entryAction will not be called (the state pointed to by entryState (after following the chain of children), however, will have its entryAction called).

Warning: The state machine cannot detect cycles in parent chains and children chains. If such cycles are present, stateM_handleEvent() will never finish due to never-ending loops.

Final state

A final state is a state that terminates the state machine. A state is considered as a final state if its numTransitions is 0:

struct state finalState = {
   .transitions = NULL,
   .numTransitions = 0,

The error state used by the state machine to indicate errors should be a final state. Any calls to stateM_handleEvent() when the current state is a final state will return stateM_noStateChange.

See Also: event; transition

Examples:: nestedTest.c, and stateMachineExample.c.

Member Data Documentation

void( * state::entryAction)(void *stateData, struct event *event)

This function is called whenever the state is being entered. May be NULL.

Note: If a state returns to itself through a transition (either directly or through a parent/group sate), its entryAction will not be called.; A group/parent state with its entryState defined will not have its entryAction called.

Parameters

stateData	the state's data will be passed.
event	the event that triggered the transition will be passed.

Examples:: nestedTest.c, and stateMachineExample.c.

void( * state::exitAction)(void *stateData, struct event *event)

This function is called whenever the state is being left. May be NULL.

Note: If a state returns to itself through a transition (either directly or through a parent/group sate), its exitAction will not be called.