QP/C++  7.0.1
Real-Time Embedded Framework
QMsm Class Reference

QM State Machine implementation strategy. More...

#include <qep.hpp>

Inheritance diagram for QMsm:
QHsm

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...
 
virtual void init (void const *const e, std::uint_fast8_t const qs_id)
 executes the top-most initial transition in QP::QHsm More...
 
virtual void init (std::uint_fast8_t const qs_id)
 overloaded init(qs_id) More...
 
virtual void dispatch (QEvt const *const e, std::uint_fast8_t const qs_id)
 Dispatches an event to QHsm. 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...
 
virtual QStateHandler getStateHandler () noexcept
 Get the current state handler of the HSM. 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

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 QP::QMsm { // inherits QP::QMsm
private:
double m_operand;
char m_display[DISP_WIDTH + 1];
std::uint8_t m_len;
std::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(ready);
QM_STATE_DECL(result);
QM_STATE_DECL(begin);
. . .
};
QM State Machine implementation strategy.
Definition: qep.hpp:482
#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:641
#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:655

Definition at line 482 of file qep.hpp.

Constructor & Destructor Documentation

◆ QMsm()

QMsm ( QStateHandler const  initial)
explicitprotectednoexcept
Description
Performs the first step of initialization by assigning the initial pseudostate to the currently active state of the state machine.
Parameters
[in]initialthe 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 74 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
Description
Executes the top-most initial transition in a MSM.
Parameters
[in]epointer to an extra parameter (might be nullptr)
[in]qs_idQS-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 92 of file qep_msm.cpp.

◆ init() [2/2]

void init ( std::uint_fast8_t const  qs_id)
overridevirtual
Description
Executes the top-most initial transition in a MSM (overloaded).
Parameters
[in]qs_idQS-id of this state machine (for QS local filter)
Attention
QP::QMsm::init() must be called exactly once before QP::QMsm::dispatch()

Reimplemented from QHsm.

Definition at line 139 of file qep_msm.cpp.

◆ dispatch()

void dispatch ( QEvt const *const  e,
std::uint_fast8_t const  qs_id 
)
overridevirtual
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]epointer to the event to be dispatched to the MSM
[in]qs_idQS-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 154 of file qep_msm.cpp.

◆ isInState()

bool isInState ( QMState const *const  st) const
noexcept
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]stpointer 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 529 of file qep_msm.cpp.

◆ stateObj()

QMState const * stateObj ( void  ) const
inlinenoexcept

Definition at line 500 of file qep.hpp.

◆ childStateObj()

QMState const * childStateObj ( QMState const *const  parent) const
noexcept
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]parentpointer 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 559 of file qep_msm.cpp.

◆ getStateHandler()

QStateHandler getStateHandler ( )
overrideprotectedvirtualnoexcept
Description
Helper function to get the current state handler of QMsm.

Reimplemented from QHsm.

Definition at line 326 of file qep_msm.cpp.

◆ isIn()

bool isIn ( QStateHandler const  s)
privatedeletenoexcept

◆ state()

QStateHandler state ( void  ) const
privatedeletenoexcept

◆ childState()

QStateHandler childState ( QStateHandler const  parent)
privatedeletenoexcept

◆ top()

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

◆ execTatbl_()

QState execTatbl_ ( QMTranActTable const *const  tatbl,
std::uint_fast8_t const  qs_id 
)
private
Description
Helper function to execute transition sequence in a tran-action table.
Parameters
[in]tatblpointer to the transition-action table
[in]qs_idQS-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 345 of file qep_msm.cpp.

◆ exitToTranSource_()

void exitToTranSource_ ( QMState const *  s,
QMState const *const  ts,
std::uint_fast8_t const  qs_id 
)
private
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]spointer to the current state
[in]tspointer to the transition source state
[in]qs_idQS-id of this state machine (for QS local filter)

Definition at line 420 of file qep_msm.cpp.

◆ enterHistory_()

QState enterHistory_ ( QMState const *const  hist,
std::uint_fast8_t const  qs_id 
)
private
Description
Static helper function to execute the segment of transition to history after entering the composite state and
Parameters
[in]histpointer to the history substate
[in]qs_idQS-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 461 of file qep_msm.cpp.

Friends And Related Function Documentation

◆ QMActive

friend class QMActive
friend

Definition at line 552 of file qep.hpp.

Field Documentation

◆ MAX_ENTRY_DEPTH_

constexpr std::int_fast8_t MAX_ENTRY_DEPTH_ {4}
staticconstexprprivate

Definition at line 547 of file qep.hpp.

◆ msm_top_s

QMState const msm_top_s
staticprivate
Initial value:
= {
nullptr,
nullptr,
nullptr,
nullptr,
nullptr
}

Definition at line 550 of file qep.hpp.


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