transition Struct Reference

Transition between a state and another state. More...

#include <stateMachine.h>

Public Attributes
int	eventType
	The event that will trigger this transition.
void *	condition
	Condition that event must fulfil.
bool(*	guard )(void *condition, struct event *event)
	Check if data passed with event fulfils a condition.
void(*	action )(void *currentStateData, struct event *event, void *newStateData)
	Function containing tasks to be performed during the transition.
struct state *	nextState
	The next state.

Detailed Description

Transition between a state and another state.

All states that are not final must have at least one transition. The transition may be guarded or not. Transitions are triggered by events. If a state has more than one transition with the same type of event (and the same condition), the first transition in the array will be run. An unconditional transition placed last in the transition array of a state can act as a "catch-all". A transition may optionally run an action, which will have the triggering event passed to it as an argument, along with the current and new states' data.

It is perfectly valid for a transition to return to the state it belongs to. Such a transition will not call the state's entry action or exit action. If there are no transitions for the current event, the state's parent will be handed the event.

Examples

• An ungarded transition to a state with no action performed:

  {
     .eventType = Event_timeout,
     .condition = NULL,
     .guard = NULL,
     .action = NULL,
     .nextState = &mainMenuState,
  },

• A guarded transition executing an action

  {
     .eventType = Event_keyboard,
     .condition = NULL,
     .guard = &ensureNumericInput,
     .action = &addToBuffer,
     .nextState = &awaitingInputState,
  },

• A guarded transition using a condition

  {
     .eventType = Event_mouse,
     .condition = boxLimits,
     .guard = &coordinatesWithinLimits,
  },

  By using conditions a more general guard function can be used, operating on the supplied argument condition. In this example, coordinatesWithinLimits checks whether the coordinates in the mouse event are within the limits of the "box".

See Also

event

state

Examples:

nestedTest.c, and stateMachineExample.c.

Member Data Documentation

void( * transition::action)(void *currentStateData, struct event *event, void *newStateData)

Function containing tasks to be performed during the transition.

The transition may optionally do some work in this function before entering the next state. May be NULL.

Parameters

currentStateData	the leaving state's data
event	the event passed to the state machine.
newStateData	the new state's (the entryState of any (chain of) parent states, not the parent state itself) data

void* transition::condition

Condition that event must fulfil.

This variable will be passed to the guard (if guard is non-NULL) and may be used as a condition that the incoming event's data must fulfil in order for the transition to be performed. By using this variable, the number of guard functions can be minimised by making them more general.

bool( * transition::guard)(void *condition, struct event *event)

Check if data passed with event fulfils a condition.

A transition may be conditional. If so, this function, if non-NULL, will be called. Its first argument will be supplied with condition, which can be compared against the payload in the event. The user may choose to use this argument or not. Only if the result is true, the transition will take place.

Parameters

condition	event (data) to compare the incoming event against.
event	the event passed to the state machine.

Returns

true if the event's data fulfils the condition, otherwise false.

Examples:

nestedTest.c.

struct state* transition::nextState

The next state.

This must point to the next state that will be entered. It cannot be NULL. If it is, the state machine will detect it and enter the error state.

---

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

• stateMachine.h