A FSM(Finite State Machine) object. More...

#include <fsm.hpp>

Inheritance diagram for qOS::stateMachine:

Collaboration diagram for qOS::stateMachine:

Public Member Functions
	stateMachine ()=default

bool	setup (const sm::stateCallback_t &topFcn, sm::state &init, sm::surroundingCallback_t sFcn=nullptr, void *pData=nullptr) noexcept
	Initializes a Finite State Machine (FSM).

bool	add (sm::state &s, const sm::stateCallback_t &sFcn, sm::state &init) noexcept
	Add the specified state to the stateMachine "Top" state.

bool	add (sm::state &s, const sm::stateCallback_t &sFcn) noexcept
	This function adds the specified state to the stateMachine "Top" state.

bool	install (queue &q) noexcept
	Install a signal queue to the provided Finite State Machine (FSM).

template<size_t numberOfSignals>
bool	install (sm::signalQueue< numberOfSignals > &sq) noexcept
	Install a signal queue to the provided Finite State Machine (FSM).

bool	sendSignal (sm::signalID sig, void *sData=nullptr, bool isUrgent=false) noexcept
	Sends a signal to a state machine.

bool	sendSignal (sm::signalIDType sig, void *sData=nullptr, bool isUrgent=false) noexcept

bool	install (sm::timeoutSpec &ts) noexcept
	Install the Timeout-specification object to target FSM and allow timed signals within states.

bool	timeoutSet (const index_t xTimeout, const qOS::duration_t t) noexcept
	Set the time for the selected built-in timeout inside the target FSM.

bool	timeoutStop (const index_t xTimeout) noexcept
	Stop the time count for the selected built-in timeout.

const sm::state &	getTop (void) const noexcept
	Retrieve a reference to the Top state of.

sm::state *const &	getCurrent (void) const noexcept
	Retrieve a reference to the state currently being evaluated.

queue *const &	getQueue (void) const noexcept
	Get a pointer to the installed queue if available.

sm::timeoutSpec *const &	getTimeSpec (void) const noexcept
	Get a pointer to the installed timeout specification if available.

void *const &	getData (void) const noexcept
	Retrieve the state machine data or storage-pointer.

void	setSurrounding (const sm::surroundingCallback_t &sFcn) noexcept
	Set the state-machine surrounding callback.

bool	run (sm::signal_t sig) noexcept
	Execute the Finite State Machine (FSM).

Detailed Description

A FSM(Finite State Machine) object.

In QuarkTS++, a state-machine must be instantiated with an object of type stateMachine.

Like any other OS object, a Finite State Machine (FSM) must be explicitly initialized before it can be used. The stateMachine::setup() initializes the instance, sets the callback for the top state, sets the initial state and the surrounding callback function.

Constructor & Destructor Documentation

◆ stateMachine()

qOS::stateMachine::stateMachine ( )

default

Member Function Documentation

◆ add() [1/2]

bool qOS::stateMachine::add	(	sm::state &	s,
		const sm::stateCallback_t &	sFcn )

inlinenoexcept

This function adds the specified state to the stateMachine "Top" state.

Parameters

[in]	s	The state object.
[in]	sFcn	The handler function associated to the state.

Prototype:

sm::status xCallback( sm::handler_t h )

qOS::sm::handler_t

The state callback argument to handle the state-machine dynamics and provide execution information....

Definition fsm.hpp:252

qOS::sm::status

status

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

Definition fsm.hpp:193

Returns: true on success, otherwise return false.

◆ add() [2/2]

bool qOS::stateMachine::add	(	sm::state &	s,
		const sm::stateCallback_t &	sFcn,
		sm::state &	init )

inlinenoexcept

Add the specified state to the stateMachine "Top" state.

Parameters

[in]	s	The state object.
[in]	sFcn	The handler function associated to the state.

Prototype:

sm::status xCallback( sm::handler_t h )

Parameters

[in] init The first child-state to be executed if the subscribed state its a parent in an hierarchical pattern. (default transition). You can ignore this argument.

Returns: true on success, otherwise return false.

◆ getCurrent()

sm::state *const & qOS::stateMachine::getCurrent ( void ) const

noexcept

Retrieve a reference to the state currently being evaluated.

Returns: A reference tot the current state.

◆ getData()

void *const & qOS::stateMachine::getData ( void ) const

noexcept

Retrieve the state machine data or storage-pointer.

Returns: The state machine data or storage-pointer.

◆ getQueue()

queue *const & qOS::stateMachine::getQueue ( void ) const

noexcept

Get a pointer to the installed queue if available.

Returns: A pointer to the installed queue if available, otherwise returns nullptr.

◆ getTimeSpec()

sm::timeoutSpec *const & qOS::stateMachine::getTimeSpec ( void ) const

noexcept

Get a pointer to the installed timeout specification if available.

Returns: A pointer to the installed timeout specification if available, otherwise returns nullptr.

◆ getTop()

const sm::state & qOS::stateMachine::getTop ( void ) const

noexcept

Retrieve a reference to the Top state of.

Returns: A reference tot the Top state.

◆ install() [1/3]

bool qOS::stateMachine::install ( queue & q )

noexcept

Install a signal queue to the provided Finite State Machine (FSM).

Precondition: Queue object should be previously initialized by using queue::setup()

Note: It is recommended to define the queue as an object of type sm::signalQueue so that the queue is configured automatically. Otherwise the user must configure it explicitly.

Attention: Queue item size = sizeof( sm::signal_t )

Parameters

[in] q The queue to be installed.

Returns: true on success, otherwise return false.

◆ install() [2/3]

template<size_t numberOfSignals>

bool qOS::stateMachine::install ( sm::signalQueue< numberOfSignals > & sq )

inlinenoexcept

Install a signal queue to the provided Finite State Machine (FSM).

Note: This function will setup the queue automatically

Parameters

[in] sq The signal queue to be installed.

Returns: true on success, otherwise return false.

◆ install() [3/3]

bool qOS::stateMachine::install ( sm::timeoutSpec & ts )

noexcept

Install the Timeout-specification object to target FSM and allow timed signals within states.

Attention: This feature its only available if the FSM has a signal-queue installed.

Precondition: This feature depends on the Timers extension. Make sure the time base is functional.

Note: You can increase the number of available timeouts instances by changing the Q_FSM_MAX_TIMEOUTS configuration macro inside config.h

Parameters

[in] ts The timeout specification object.

Returns: Returns true on success, otherwise returns false.

◆ run()

bool qOS::stateMachine::run ( sm::signal_t sig )

noexcept

Execute the Finite State Machine (FSM).

See also: core::add()

Parameters

[in] sig User-defined signal (this value will be ignored if the installed queue has items available)

Note: A signal coming from the signal-queue has the higher precedence. The user-defined signal can be overridden

Returns: true if the signal was successfully handled, otherwise returns false.

◆ sendSignal() [1/2]

bool qOS::stateMachine::sendSignal	(	sm::signalID	sig,
		void *	sData = nullptr,
		bool	isUrgent = false )

noexcept

Sends a signal to a state machine.

Note: If the signal queue is not available, an exclusion variable will be used.This means that the signal cannot be sent until the variable is empty. (the signal was handled by the state-machine engine).

Warning: Data associated to the signal is not deep-copied to a queue or any buffer. It's only data pointer (address in memory) that is shallow-copied to a signal queue so it has to point to a globally accessible memory. If it pointed to a sender's local variable (from the stack) it would be invalid after sender returns from the function that sends the signal.

Note: The signal-queue event has the highest precedence.

Parameters

[in]	sig	The user-defined signal.
[in]	sData	The data associated to the signal.
[in]	isUrgent	If true, the signal will be sent to the front of the queue. (only if the there is a signal-queue available)

Returns: true if the provided signal was successfully delivered to the state machine , otherwise return false. false if there is a queue, and the signal cannot be inserted because it is full.

◆ sendSignal() [2/2]

bool qOS::stateMachine::sendSignal	(	sm::signalIDType	sig,
		void *	sData = nullptr,
		bool	isUrgent = false )

inlinenoexcept

◆ setSurrounding()

void qOS::stateMachine::setSurrounding ( const sm::surroundingCallback_t & sFcn )

noexcept

Set the state-machine surrounding callback.

Parameters

[in] sFcn The surrounding callback function.

◆ setup()

bool qOS::stateMachine::setup	(	const sm::stateCallback_t &	topFcn,
		sm::state &	init,
		sm::surroundingCallback_t	sFcn = nullptr,
		void *	pData = nullptr )

inlinenoexcept

Initializes a Finite State Machine (FSM).

See also: core::add()

Note: This API also initializes the top state.

Parameters

[in]	topFcn	The callback for the "Top" state.
[in]	init	The first state to be executed (init-state or default transition).
[in]	sFcn	The surrounding callback. To ignore pass `nullptr`.
[in]	pData	Represents the FSM arguments. User storage pointer. To ignore pass `nullptr`.

Returns: Returns true on Success, otherwise returns false.

◆ timeoutSet()

bool qOS::stateMachine::timeoutSet	(	const index_t	xTimeout,
		const qOS::duration_t	t )

noexcept

Set the time for the selected built-in timeout inside the target FSM.

Precondition: Requires an installed timeout-specification. For this use stateMachine::install; Requires an installed signal-queue. For this use stateMachine::install

Parameters

[in]	xTimeout	The index of the requested timeout (0, 1, 2 ... (`Q_FSM_MAX_TIMEOUTS-1`) )
[in]	t	The specified time given in milliseconds.

Returns: Returns true on success, otherwise returns false.

◆ timeoutStop()

bool qOS::stateMachine::timeoutStop ( const index_t xTimeout )

noexcept

Stop the time count for the selected built-in timeout.

Precondition: Requires an installed timeout-specification. For this use stateMachine::install; Requires an installed signal-queue. For this use stateMachine::install

Parameters

[in] xTimeout The index of the timeout (0, 1, 2 ... (Q_FSM_MAX_TIMEOUTS-1) )

Returns: Returns true on success, otherwise returns false.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ stateMachine()

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ getCurrent()

◆ getData()

◆ getQueue()

◆ getTimeSpec()

◆ getTop()

◆ install() [1/3]

◆ install() [2/3]

◆ install() [3/3]

◆ run()

◆ sendSignal() [1/2]

◆ sendSignal() [2/2]

◆ setSurrounding()

◆ setup()

◆ timeoutSet()

◆ timeoutStop()