QM State Machine implementation strategy. More...

#include <qep.hpp>

Inheritance diagram for QMsm:

Collaboration diagram for QMsm:

Public Member Functions
void	init (void const *const e, std::uint_fast8_t const qs_id) override
	Performs the second step of SM initialization by triggering the top-most initial transition. More...

void	init (std::uint_fast8_t const qs_id) override
	overloaded init(qs_id) More...

void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id) override
	Dispatches an event to a HSM. More...

bool	isInState (QMState const *const st) const noexcept
	Tests if a given state is part of the active state configuration. More...

QMState const *	stateObj (void) const noexcept
	Return the current active state object (read only) More...

QMState const *	childStateObj (QMState const *const parent) const noexcept
	Obtain the current active child state of a given parent (read only) More...

Public Member Functions inherited from QHsm
virtual	~QHsm ()
	virtual destructor More...

bool	isIn (QStateHandler const s) noexcept
	Tests if a given state is part of the current active state configuration. More...

QStateHandler	state (void) const noexcept
	Obtain the current state (state handler function) More...

QStateHandler	childState (QStateHandler const parent) noexcept
	Obtain the current active child state of a given parent. More...

Protected Member Functions
	QMsm (QStateHandler const initial) noexcept
	Protected constructor. More...

QStateHandler	getStateHandler () noexcept override
	Get the current state handler of the QMsm. More...

Protected Member Functions inherited from QHsm
	QHsm (QStateHandler const initial) noexcept
	Protected constructor of QHsm. More...

QState	tran (QStateHandler const target) noexcept
	Helper function to specify a state transition. More...

QState	tran_hist (QStateHandler const hist) noexcept
	Helper function to specify a transition to history. More...

QState	super (QStateHandler const superstate) noexcept
	Helper function to specify the superstate of a given state. More...

QState	qm_tran (void const *const tatbl) noexcept
	Helper function to specify a regular state transition in a QM state-handler. More...

QState	qm_tran_hist (QMState const const hist, void const const tatbl) noexcept
	Helper function to specifiy a transition to history in a QM state-handler. More...

QState	qm_tran_init (void const *const tatbl) noexcept
	Helper function to specify an initial state transition in a QM state-handler. More...

QState	qm_tran_ep (void const *const tatbl) noexcept
	Helper function to specify a transition to an entry point to a submachine state in a QM state-handler. More...

QState	qm_tran_xp (QActionHandler const xp, void const *const tatbl) noexcept
	Helper function to specify a transition to an exit point from a submachine state in a QM state-handler. More...

QState	qm_entry (QMState const *const s) noexcept
	Helper function to specify a state entry in a QM state-handler. More...

QState	qm_exit (QMState const *const s) noexcept
	Helper function to specify a state exit in a QM state-handler. More...

QState	qm_sm_exit (QMState const *const s) noexcept
	Helper function to specify a submachine exit in a QM state-handler. More...

QState	qm_super_sub (QMState const *const s) noexcept
	Helper function to call in a QM state-handler when it passes the event to the host submachine state to handle an event. More...

Private Member Functions
bool	isIn (QStateHandler const s) noexcept=delete
	disallow inhertited isIn() function in QP::QMsm and subclasses More...

QStateHandler	state (void) const noexcept=delete
	disallow inhertited state() function in QP::QMsm and subclasses More...

QStateHandler	childState (QStateHandler const parent) noexcept=delete
	disallow inhertited childState() function in QP::QMsm and subclasses More...

QState	execTatbl_ (QMTranActTable const *const tatbl, std::uint_fast8_t const qs_id)
	Internal helper function to execute a transition-action table. More...

void	exitToTranSource_ (QMState const s, QMState const const ts, std::uint_fast8_t const qs_id)
	Internal helper function to exit current state to transition source. More...

QState	enterHistory_ (QMState const *const hist, std::uint_fast8_t const qs_id)
	Internal helper function to enter state history. More...

Static Private Member Functions
static QState	top (void const me, QEvt const const e) noexcept=delete
	disallow inhertited top() function in QP::QMsm and subclasses More...

Static Private Attributes
static constexpr std::int_fast8_t	MAX_ENTRY_DEPTH_ {4}
	maximum depth of implemented entry levels for transitions to history More...

static QMState const	msm_top_s
	the top state object for the QMsm More...

Friends
class	QMActive

Additional Inherited Members
Static Public Member Functions inherited from QHsm
static QState	top (void const me, QEvt const const e) noexcept
	the top-state. More...

Static Public Attributes inherited from QHsm
static constexpr QState	Q_RET_SUPER {static_cast<QState>(0)}
	event passed to the superstate to handle More...

static constexpr QState	Q_RET_SUPER_SUB {static_cast<QState>(1)}
	event passed to submachine superstate More...

static constexpr QState	Q_RET_UNHANDLED {static_cast<QState>(2)}
	event unhandled due to a guard evaluating to 'false' More...

static constexpr QState	Q_RET_HANDLED {static_cast<QState>(3)}
	event handled (internal transition) More...

static constexpr QState	Q_RET_IGNORED {static_cast<QState>(4)}
	event silently ignored (bubbled up to top) More...

static constexpr QState	Q_RET_ENTRY {static_cast<QState>(5)}
	state entry action executed More...

static constexpr QState	Q_RET_EXIT {static_cast<QState>(6)}
	state exit action executed More...

static constexpr QState	Q_RET_NULL {static_cast<QState>(7)}
	return value without any effect More...

static constexpr QState	Q_RET_TRAN {static_cast<QState>(8)}
	regular transition taken More...

static constexpr QState	Q_RET_TRAN_INIT {static_cast<QState>(9)}
	initial transition taken More...

static constexpr QState	Q_RET_TRAN_EP {static_cast<QState>(10)}
	entry-point transition into a submachine More...

static constexpr QState	Q_RET_TRAN_HIST {static_cast<QState>(11)}
	transition to history of a given state More...

static constexpr QState	Q_RET_TRAN_XP {static_cast<QState>(12)}
	exit-point transition out of a submachine More...

Protected Types inherited from QHsm
enum	ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG }

Detailed Description

QM State Machine implementation strategy.

Description: QMsm (QM State Machine) provides a more efficient state machine implementation strategy than QHsm, but requires the use of the QM modeling tool, but are the fastest and need the least run-time support (the smallest event-processor taking up the least code space).

Note: QMsm is not intended to be instantiated directly, but rather serves as the base class for derivation of state machines in the application code.

Usage: The following example illustrates how to derive a state machine class from QMsm. Please note that the QMsm member 'super' is defined as the first member of the derived struct.
class Calc : public QMsm { // derived from QMsm

private:

double m_operand;

char m_display[DISP_WIDTH + 1];

uint8_t m_len;

uint8_t m_opKey;

public:

Calc() // constructor

: QMsm(&initial)) { // superclass' constructor

}

protected:

// NOTE: QMsm state machine code is not intended for manual

// coding but rather needs to be generated automatically by

// the QM modeling tool

QM_STATE_DECL(initial);

QM_STATE_DECL( on);

QM_ACTION_DECL(on_e);

QM_STATE_DECL(ready);

QM_STATE_DECL(result);

QM_STATE_DECL(begin);

. . .

};

uint8_t
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: 16bit/stdint.h:29

QP::QHsm::QMsm
friend class QMsm
Definition: qep.hpp:469

QM_STATE_DECL
#define QM_STATE_DECL(state_)
Macro to generate a declaration of a state-handler, state-caller and a state-object for a given state...
Definition: qep.hpp:662

QM_ACTION_DECL
#define QM_ACTION_DECL(action_)
Macro to generate a declaration of an action-handler and action-caller in a subclass of QP::QMsm.
Definition: qep.hpp:676

Definition at line 501 of file qep.hpp.

Constructor & Destructor Documentation

◆ QMsm()

QMsm ( QStateHandler const initial )

explicitprotectednoexcept

Protected constructor.

Description: Performs the first step of initialization by assigning the initial pseudostate to the currently active state of the state machine.

Parameters

[in] initial the top-most initial transition for the MSM.

Note: The constructor is protected to prevent direct instantiating of the QP::QMsm objects. This class is intended for subclassing only.

See also: The QP::QMsm example illustrates how to use the QMsm constructor in the constructor initializer list of the derived state machines.

Definition at line 83 of file qep_msm.cpp.

Member Function Documentation

◆ init() [1/2]

void init	(	void const *const	e,
		std::uint_fast8_t const	qs_id
	)

overridevirtual

Performs the second step of SM initialization by triggering the top-most initial transition.

Description: Executes the top-most initial transition in a MSM.

Parameters

[in]	e	pointer to an extra parameter (might be nullptr)
[in]	qs_id	QS-id of this state machine (for QS local filter)

Attention: QP::QMsm::init() must be called exactly once before QP::QMsm::dispatch()

Precondition: the top-most initial transition must be initialized, and the initial transition must not be taken yet.

Reimplemented from QHsm.

Definition at line 101 of file qep_msm.cpp.

◆ init() [2/2]

void init ( std::uint_fast8_t const qs_id )

inlineoverridevirtual

overloaded init(qs_id)

Reimplemented from QHsm.

Definition at line 507 of file qep.hpp.

◆ dispatch()

void dispatch	(	QEvt const *const	e,
		std::uint_fast8_t const	qs_id
	)

overridevirtual

Dispatches an event to a HSM.

Description: Dispatches an event for processing to a meta state machine (MSM). The processing of an event represents one run-to-completion (RTC) step.

Parameters

[in]	e	pointer to the event to be dispatched to the MSM
[in]	qs_id	QS-id of this state machine (for QS local filter)

Note: Must be called after QP::QMsm::init().

Precondition: current state must be initialized

Reimplemented from QHsm.

Definition at line 149 of file qep_msm.cpp.

◆ isInState()

bool isInState ( QMState const *const st ) const

noexcept

Tests if a given state is part of the active state configuration.

Description: Tests if a state machine derived from QMsm is-in a given state.

Note: For a MSM, to "be-in" a state means also to "be-in" a superstate of of the state.

Parameters

[in] st pointer to the QMState object that corresponds to the tested state.

Returns: 'true' if the MSM is in the st and 'false' otherwise

Definition at line 524 of file qep_msm.cpp.

◆ stateObj()

QMState const* stateObj ( void ) const

inlinenoexcept

Return the current active state object (read only)

Definition at line 519 of file qep.hpp.

◆ childStateObj()

QMState const * childStateObj ( QMState const *const parent ) const

noexcept

Obtain the current active child state of a given parent (read only)

Description: Finds the child state of the given parent, such that this child state is an ancestor of the currently active state. The main purpose of this function is to support shallow history transitions in state machines derived from QMsm.

Parameters

[in] parent pointer to the state-handler object

Returns: the child of a given parent state, which is an ancestor of the currently active state. For the corner case when the currently active state is the given parent state, function returns the parent state.

Postcondition: the child must be found

Definition at line 554 of file qep_msm.cpp.

◆ getStateHandler()

QStateHandler getStateHandler ( )

overrideprotectedvirtualnoexcept

Get the current state handler of the QMsm.

Description: Helper function to get the current state handler of QMsm.

Reimplemented from QHsm.

Definition at line 321 of file qep_msm.cpp.

◆ isIn()

bool isIn ( QStateHandler const s )

privatedeletenoexcept

disallow inhertited isIn() function in QP::QMsm and subclasses

See also: QP::QMsm::isInState()

◆ state()

QStateHandler state ( void ) const

privatedeletenoexcept

disallow inhertited state() function in QP::QMsm and subclasses

See also: QP::QMsm::stateObj()

◆ childState()

QStateHandler childState ( QStateHandler const parent )

privatedeletenoexcept

disallow inhertited childState() function in QP::QMsm and subclasses

See also: QP::QMsm::childStateObj()

◆ top()

static QState top	(	void *const	me,
		QEvt const *const	e
	)

staticprivatedeletenoexcept

disallow inhertited top() function in QP::QMsm and subclasses

See also: QP::QMsm::msm_top_s

◆ execTatbl_()

QState execTatbl_	(	QMTranActTable const *const	tatbl,
		std::uint_fast8_t const	qs_id
	)

private

Internal helper function to execute a transition-action table.

Description: Helper function to execute transition sequence in a tran-action table.

Parameters

[in]	tatbl	pointer to the transition-action table
[in]	qs_id	QS-id of this state machine (for QS local filter)

Returns: the status of the last action from the transition-action table.

Note: This function is for internal use inside the QEP event processor and should not be called directly from the applications.

Precondition: the transition-action table pointer must not be nullptr

Definition at line 340 of file qep_msm.cpp.

◆ exitToTranSource_()

void exitToTranSource_	(	QMState const *	s,
		QMState const *const	ts,
		std::uint_fast8_t const	qs_id
	)

private

Internal helper function to exit current state to transition source.

Description: Helper function to exit the current state configuration to the transition source, which is a hierarchical state machine might be a superstate of the current state.

Parameters

[in]	s	pointer to the current state
[in]	ts	pointer to the transition source state
[in]	qs_id	QS-id of this state machine (for QS local filter)

Definition at line 415 of file qep_msm.cpp.

◆ enterHistory_()

QState enterHistory_	(	QMState const *const	hist,
		std::uint_fast8_t const	qs_id
	)

private

Internal helper function to enter state history.

Description: Static helper function to execute the segment of transition to history after entering the composite state and

Parameters

[in]	hist	pointer to the history substate
[in]	qs_id	QS-id of this state machine (for QS local filter)

Returns: QP::Q_RET_INIT, if an initial transition has been executed in the last entered state or QP::Q_RET_NULL if no such transition was taken.

Definition at line 456 of file qep_msm.cpp.

Friends And Related Function Documentation

◆ QMActive

friend class QMActive

friend

Definition at line 571 of file qep.hpp.

Field Documentation

◆ MAX_ENTRY_DEPTH_

constexpr std::int_fast8_t MAX_ENTRY_DEPTH_ {4}

staticconstexprprivate

maximum depth of implemented entry levels for transitions to history

Definition at line 566 of file qep.hpp.

◆ msm_top_s

QMState const msm_top_s

staticprivate

Initial value:

= {
    nullptr,
    nullptr,
    nullptr,
    nullptr,
    nullptr
}

the top state object for the QMsm

Definition at line 569 of file qep.hpp.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Member Functions

Private Member Functions

Static Private Member Functions

Static Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QMsm()

Member Function Documentation

◆ init() [1/2]

◆ init() [2/2]

◆ dispatch()

◆ isInState()

◆ stateObj()

◆ childStateObj()

◆ getStateHandler()

◆ isIn()

◆ state()

◆ childState()

◆ top()

◆ execTatbl_()

◆ exitToTranSource_()

◆ enterHistory_()

Friends And Related Function Documentation

◆ QMActive

Field Documentation

◆ MAX_ENTRY_DEPTH_

◆ msm_top_s