Finite State Machines

API interface of the Finite State Machines (FSM) extension. More...

Collaboration diagram for Finite State Machines:

Namespaces
namespace	qOS::sm
	Finite State Machine interfaces.

Classes
struct	qOS::sm::signal_t
	The type to be used as a container variable for a signal. More...
struct	qOS::sm::signalQueue< numberOfSignals >
	The type of a FSM signal-queue. More...
class	qOS::sm::handler_t
	The state callback argument to handle the state-machine dynamics and provide execution information. Some methods can be written to perform state-transitions. More...
struct	qOS::sm::timeoutStateDefinition
	This type should be used to define an item for a timeout-specification table. More...
struct	qOS::sm::transition
	This structure should be used to define an item for a state transition table. More...
class	qOS::sm::state
	A state object. More...
class	qOS::sm::timeoutSpec
	A FSM Timeout-specification object. More...
class	qOS::stateMachine
	A FSM(Finite State Machine) object. More...
class	qOS::sm::signalPublisher
	An object to subscribe FSM(Finite State Machine) objects to specific user-defined signals. More...

Typedefs
using	qOS::sm::signalIDType
using	qOS::sm::stateCallback_t
	Pointer to a function that represents a state callback.
using	qOS::sm::surroundingCallback_t
	Pointer to a function that represents a surrounding callback.
using	qOS::sm::signalAction_t
	Pointer to a function that represents a signal guard/action.
using	qOS::sm::timeoutSpecOption_t
	A typedef to hold the timeout specification options.

Enumerations
enum	qOS::sm::signalID : signalIDType {   qOS::sm::SIGNAL_START , qOS::sm::SIGNAL_EXIT , qOS::sm::SIGNAL_ENTRY , qOS::sm::SIGNAL_NONE ,   qOS::sm::SIGNAL_TIMEOUT0 , qOS::sm::SIGNAL_TIMEOUT1 , qOS::sm::SIGNAL_TIMEOUT2 }
	The type for signal ID. More...
enum	qOS::sm::status : int16_t {   qOS::sm::BEFORE_ANY , qOS::sm::ABSENT , qOS::sm::FAILURE , qOS::sm::SUCCESS ,   qOS::sm::SIGNAL_HANDLED }
	This enumeration defines the built-in state-execution status values that can be used as return value in a state callback. More...
enum	qOS::sm::historyMode : uint8_t { qOS::sm::NO_HISTORY , qOS::sm::SHALLOW_HISTORY , qOS::sm::DEEP_HISTORY }
	This enumeration defines the possible modes to perform a transition to history. More...

Functions
constexpr signalID	qOS::sm::SIGNAL_TIMEOUT (index_t iTm)
	Built-in signal to indicate that a timeout expiration event occurs.
constexpr signalID	qOS::sm::SIGNAL_USER (uint32_t s)
	Function to define a user-defined signal.
constexpr timeoutSpecOption_t	qOS::sm::TIMEOUT_INDEX (index_t i)
	Timeout-specification option. Should be used only to specify which timeout signal to use.
constexpr timeoutSpecOption_t	qOS::sm::TIMEOUT_USE_SIGNAL (index_t i)
	Timeout-specification option. Should be used only to specify which timeout signal to use.
bool	qOS::core::add (task &Task, stateMachine &m, const priority_t p, const duration_t t, const taskState s=taskState::ENABLED_STATE, void *arg=nullptr) noexcept
	Add a task to the scheduling scheme running a dedicated state-machine. The task is scheduled to run every t time units in task::PERIODIC mode. The event info will be available as a generic pointer inside the sm::handler_t::Data field.

Variables
const timeoutSpecOption_t	qOS::sm::TIMEOUT_SET_ENTRY
	This timeout-specification option its used to specify that the engine should set the timeout when the specified state its entering.
const timeoutSpecOption_t	qOS::sm::TIMEOUT_RST_ENTRY
	This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its entering.
const timeoutSpecOption_t	qOS::sm::TIMEOUT_SET_EXIT
	This timeout-specification option its used to specify that the engine should set the timeout when the specified state its exiting*.
const timeoutSpecOption_t	qOS::sm::TIMEOUT_RST_EXIT
	This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its exiting*.
const timeoutSpecOption_t	qOS::sm::TIMEOUT_KEEP_IF_SET
	This timeout-specification option its used to specify that the engine should set the timeout only if it is in reset state.
const timeoutSpecOption_t	qOS::sm::TIMEOUT_PERIODIC
	This timeout-specification option its used setup the timeout in periodic mode.

Detailed Description

API interface of the Finite State Machines (FSM) extension.

Typedef Documentation

signalAction_t

using qOS::sm::signalAction_t

Pointer to a function that represents a signal guard/action.

bool signalAction_Callback( sm::handler_t h ) {
      bool retVal = false
      if ( ConditionGuard ) {
          performSomeAction();
          retVal = true;
      }
      return retVal;
}

Parameters

h	The object that handles the state machine

Returns

A boolean value that allow or rejects the state transition. If the value is false the event-signal is rejected, preventing the state transition to be performed.

signalIDType

using qOS::sm::signalIDType

stateCallback_t

using qOS::sm::stateCallback_t

Pointer to a function that represents a state callback.

sm::status myState_Callback( sm::handler_t h ) {
      sm::status retVal = sm::status::SUCCESS;
      switch ( h.signal() ) {
          case sm::SIGNAL_ENTRY:
              break;
          case sm::SIGNAL_EXIT:
              break;
          case USER_SIGNAL:
              retVal = sm::status::SIGNAL_HANDLED;
              break;
          default:
              break;
      return retVal;
}

Parameters

h	The object that handles the state machine

Returns

The execution status of the state.

surroundingCallback_t

using qOS::sm::surroundingCallback_t

Pointer to a function that represents a surrounding callback.

void surrounding_Callback( sm::handler_t h ) {
      switch ( h.lastStatus() ) {
          case sm::status::BEFORE_ANY:
              break;
          case sm::status::SUCCESS:
              break;
          case sm::status::FAILURE:
              break;
          default:
              break;
}

Parameters

h	The object that handles the state machine

Returns

none.

timeoutSpecOption_t

using qOS::sm::timeoutSpecOption_t

A typedef to hold the timeout specification options.

Enumeration Type Documentation

historyMode

enum qOS::sm::historyMode : uint8_t

This enumeration defines the possible modes to perform a transition to history.

Enumerator
NO_HISTORY	History is not preserved. Composite states will start according to their default transition.
SHALLOW_HISTORY	History will be kept to allow the return to only the top-most sub-state of the most recent state configuration, which is entered using the default entry rule.
DEEP_HISTORY	History will be kept to allow full state configuration of the most recent visit to the containing region..

signalID

enum qOS::sm::signalID : signalIDType

The type for signal ID.

Enumerator
SIGNAL_START	Built-in signal that can be used to set a nested initial-transition (aka default transition) by using the sm::handler_t::startState() method. Note Transitions by setting the sm::handler_t::nextState() member are not allowed here
SIGNAL_EXIT	Built-in signal to indicate if the current state has just exit to another state. Note Transitions are not allowed here
SIGNAL_ENTRY	Built-in signal to indicate if the current state has just entered from another state. Note Transitions are not allowed here
SIGNAL_NONE	Built-in signal to indicate that there is not signal available.
SIGNAL_TIMEOUT0	Built-in signal to indicate that the timeout at index 0 expired.
SIGNAL_TIMEOUT1	Built-in signal to indicate that the timeout at index 1 expired.
SIGNAL_TIMEOUT2	Built-in signal to indicate that the timeout at index 2 expired.

status

enum qOS::sm::status : int16_t

This enumeration defines the built-in state-execution status values that can be used as return value in a state callback.

Enumerator
BEFORE_ANY	(Only available in the surrounding callback) Indicates an execution of the surrounding callback before launching the state callback
ABSENT	Not to be used at the application level. This value is reserved for use.
FAILURE	To indicate that the state had a failure or abnormal execution. It can be used to handle exceptions.
SUCCESS	To indicate that the status was successful.
SIGNAL_HANDLED	To indicate that the state handled the signal and therefore it is not necessary to continue propagating the signal through the rest of the hierarchy.

Function Documentation

add()

bool qOS::core::add ( task & Task, stateMachine & m, const priority_t p, const duration_t t, const taskState s = taskState::ENABLED_STATE, void * arg = nullptr )

noexcept

Add a task to the scheduling scheme running a dedicated state-machine. The task is scheduled to run every t time units in task::PERIODIC mode. The event info will be available as a generic pointer inside the sm::handler_t::Data field.

Precondition

The State-machine object should be previously configured with qOS::stateMachine::setup()

See also

qOS::stateMachine::setup()

Parameters

[in]	Task	A pointer to the task node.
[in]	m	A pointer to the Finite State-Machine (FSM) object.
[in]	p	Task priority Value. [0(min) - Q_PRIORITY_LEVELS (max)]
[in]	t	Execution time interval given in milliseconds. For immediate execution ( t = clock::IMMEDIATE ).
[in]	s	Specifies the initial operational state of the task (taskState::ENABLED_STATE, taskState::DISABLED_STATE, taskState::AWAKE_STATE or taskState::AWAKE_STATE(implies taskState::ENABLED_STATE,)).
[in]	arg	Represents the task arguments. All arguments must be passed by reference and cast to void*.

Returns

Returns true on success, otherwise returns false.

SIGNAL_TIMEOUT()

signalID qOS::sm::SIGNAL_TIMEOUT ( index_t iTm )

constexpr

Built-in signal to indicate that a timeout expiration event occurs.

Parameters

iTm	The index of the timeout (0, 1, 2... ( Q_FSM_MAX_TIMEOUTS-1 ) )

Returns

The built-int timeout signal at index iTm.

SIGNAL_USER()

signalID qOS::sm::SIGNAL_USER ( uint32_t s )

constexpr

Function to define a user-defined signal.

Parameters

s	The value for the user-defined signal.

Returns

The user defined signal as a signalID type

TIMEOUT_INDEX()

timeoutSpecOption_t qOS::sm::TIMEOUT_INDEX ( index_t i )

constexpr

Timeout-specification option. Should be used only to specify which timeout signal to use.

See also

TIMEOUT_USE_SIGNAL()

Note

Can be combined with a bitwise OR

TIMEOUT_USE_SIGNAL()

timeoutSpecOption_t qOS::sm::TIMEOUT_USE_SIGNAL ( index_t i )

constexpr

Timeout-specification option. Should be used only to specify which timeout signal to use.

See also

TIMEOUT_INDEX()

Note

Can be combined with a bitwise OR

Variable Documentation

TIMEOUT_KEEP_IF_SET

const timeoutSpecOption_t qOS::sm::TIMEOUT_KEEP_IF_SET

extern

This timeout-specification option its used to specify that the engine should set the timeout only if it is in reset state.

Note

Can be combined with a bitwise OR

TIMEOUT_PERIODIC

const timeoutSpecOption_t qOS::sm::TIMEOUT_PERIODIC

extern

This timeout-specification option its used setup the timeout in periodic mode.

Note

Can be combined with a bitwise OR

TIMEOUT_RST_ENTRY

const timeoutSpecOption_t qOS::sm::TIMEOUT_RST_ENTRY

extern

This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its entering.

Note

Can be combined with a bitwise OR

TIMEOUT_RST_EXIT

const timeoutSpecOption_t qOS::sm::TIMEOUT_RST_EXIT

extern

This timeout-specification option its used to specify that the engine should reset the timeout when the specified state its exiting*.

Note

Can be combined with a bitwise OR

TIMEOUT_SET_ENTRY

const timeoutSpecOption_t qOS::sm::TIMEOUT_SET_ENTRY

extern

This timeout-specification option its used to specify that the engine should set the timeout when the specified state its entering.

Note

Can be combined with a bitwise OR

TIMEOUT_SET_EXIT

const timeoutSpecOption_t qOS::sm::TIMEOUT_SET_EXIT

extern

This timeout-specification option its used to specify that the engine should set the timeout when the specified state its exiting*.

Note

Can be combined with a bitwise OR