Out-of-office display, GFX
 All Classes Files Functions Variables Enumerations Enumerator Groups
Public Attributes | List of all members
state Struct Reference

State. More...

#include <stateMachine.h>

Public Attributes

struct stateparentState
 If the state has a parent state, this pointer must be non-NULL.
struct stateentryState
 If this state is a parent state, this pointer may point to a child state that serves as an entry point.
struct transitiontransitions
 An array of transitions for the state.
size_t numTransitions
 Number of transitions in the array.
void * data
 Data that will be available for the state in its entryAction and exitAction.
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 acts 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.

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 an event does not trigger a transition in a state and if the state has a defined parent state, the event will be passed to the parent state. 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 from 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 },
},
.data = normalStateData,
.entryAction = &doSomething,
.exitAction = &cleanUp,
};

In this example, normalState is a childe 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.

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.

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

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.

Final states must have numTransitions set to 0.

Note
A state can only be a parent or a child (only parentState or entryState, but not both, can be defined at a time).
See Also
event
transition
Examples:
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.
Parameters
stateDatathe state's data will be passed.
eventthe event that triggered a transition will be passed.
Examples:
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.
Parameters
stateDatathe state's data will be passed.
eventthe event that triggered a transition will be passed.

The documentation for this struct was generated from the following file: