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

Hierarchical State Machine base class. More...

#include <qep.hpp>

Inheritance diagram for QHsm:
QActive QHsmDummy QMsm QActiveDummy QMActive QTicker QXThread

Public Member Functions

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...
 

Static Public Member Functions

static QState top (void *const me, QEvt const *const e) noexcept
 The top-state handler. More...
 

Static Public Attributes

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

enum  ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG }
 

Protected Member Functions

 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

std::int_fast8_t hsm_tran (QStateHandler(&path)[MAX_NEST_DEPTH_], std::uint_fast8_t const qs_id)
 Helper function to take a transition in QP::QHsm. More...
 

Private Attributes

QHsmAttr m_state
 current active state (state-variable) More...
 
QHsmAttr m_temp
 temporary: transition chain, target state, etc. More...
 

Static Private Attributes

static constexpr std::int_fast8_t MAX_NEST_DEPTH_ {6}
 maximum nesting depth of states in HSM More...
 

Friends

class QMsm
 
class QActive
 
class QMActive
 
class QF
 
class QS
 
class QXK
 
class QXThread
 
class QXMutex
 
class QXSemaphore
 
class QHsmDummy
 
class QActiveDummy
 

Detailed Description

Description
QHsm represents a Hierarchical State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, and initial transitions in any composite state.

QHsm is also the base class for the QMsm state machine, which provides a superior efficiency, but requires the use of the QM modeling tool to generate code.

Note
QHsm 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 QHsm.
class Calc : public QP::QHsm { // inherits QP::QHsm
private:
double m_operand1;
double m_operand2;
char m_display[DISP_WIDTH + 1];
std::uint8_t m_len;
std::uint8_t m_opKey;
public:
Calc() // constructor
: QP::QHsm(Calc)) { // superclass' constructor
}
protected:
Q_STATE_DECL(initial);
Q_STATE_DECL(error);
Q_STATE_DECL(ready);
Q_STATE_DECL(result);
Q_STATE_DECL(begin);
. . .
};
Hierarchical State Machine base class.
Definition: qep.hpp:258
namespace associated with the QP/C++ framework
Definition: exa_native.dox:1
#define Q_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:805

Definition at line 258 of file qep.hpp.

Member Enumeration Documentation

◆ ReservedHsmSignals

enum ReservedHsmSignals : QSignal
protected
Enumerator
Q_ENTRY_SIG 

signal for entry actions

Q_EXIT_SIG 

signal for exit actions

Q_INIT_SIG 

signal for nested initial transitions

Definition at line 436 of file qep.hpp.

Constructor & Destructor Documentation

◆ QHsm()

QHsm ( QStateHandler const  initial)
explicitprotectednoexcept
Description
Performs the first step of HSM initialization by assigning the initial pseudostate to the currently active state of the state machine.
Parameters
[in]initialpointer to the top-most initial state-handler function in the derived state machine
Traceability:
traces to: RQP103

Definition at line 109 of file qep_hsm.cpp.

Member Function Documentation

◆ init() [1/2]

void init ( void const *const  e,
std::uint_fast8_t const  qs_id 
)
virtual
Description
Executes the top-most initial transition in a HSM.
Parameters
[in]epointer to an extra parameter (might be NULL)
[in]qs_idQS-id of this state machine (for QS local filter)
Note
Must be called exactly once before the QP::QHsm::dispatch().
Traceability:

traces to: RQP103

traces to: RQP120I

traces to: RQP120D

Precondition
ctor must have been executed and initial tran NOT taken

Reimplemented in QTicker, QHsmDummy, QActiveDummy, QXThread, QMsm, and QMActive.

Definition at line 115 of file qep_hsm.cpp.

◆ init() [2/2]

virtual void init ( std::uint_fast8_t const  qs_id)
inlinevirtual

Reimplemented in QTicker, QHsmDummy, QActiveDummy, QXThread, QMsm, and QMActive.

Definition at line 286 of file qep.hpp.

◆ dispatch()

void dispatch ( QEvt const *const  e,
std::uint_fast8_t const  qs_id 
)
virtual
Description
Dispatches an event for processing to a hierarchical state machine. The processing of an event represents one run-to-completion (RTC) step.
Parameters
[in]epointer to the event to be dispatched to the HSM
[in]qs_idQS-id of this state machine (for QS local filter)
Note
This state machine must be initialized by calling QP::QHsm::init() exactly once before calling QP::QHsm::dispatch().
Traceability:

traces to: RQP103

traces to: RQP120A

traces to: RQP120B

traces to: RQP120C

traces to: RQP120D

traces to: RQP120E

Precondition
the current state must be initialized and the state configuration must be stable
Traceability:
traces to: RQP120A
Traceability:
traces to: RQP120E
Traceability:
traces to: RQP120C
Traceability:
traces to: RQP120B
Traceability:
traces to: RQP120I

Reimplemented in QTicker, QHsmDummy, QActiveDummy, QXThread, QMsm, and QMActive.

Definition at line 192 of file qep_hsm.cpp.

◆ isIn()

bool isIn ( QStateHandler const  s)
noexcept
Description
Tests if a state machine derived from QHsm is-in a given state.
Note
For a HSM, to "be in a state" means also to be in a superstate of of the state.
Parameters
[in]spointer to the state-handler function to be tested
Returns
'true' if the HSM is in the state and 'false' otherwise
Traceability:

traces to: RQP103

traces to: RQP120S

Precondition
state configuration must be stable

Definition at line 486 of file qep_hsm.cpp.

◆ state()

QStateHandler state ( void  ) const
inlinenoexcept
Note
used in the QM code generation

Definition at line 332 of file qep.hpp.

◆ childState()

QStateHandler childState ( QStateHandler const  parent)
noexcept
Note
used in the QM code generation
Postcondition
the child must be confirmed

Definition at line 511 of file qep_hsm.cpp.

◆ top()

QState top ( void *const  me,
QEvt const *const  e 
)
staticnoexcept
Description
The QP::QHsm::top() state handler is the ultimate root of state hierarchy in all HSMs derived from QP::QHsm.
Parameters
[in]mepointer to the HSM instance
[in]epointer to the event to be dispatched to the HSM
Returns
Always returns Q_RET_IGNORED, which means that the top state ignores all events.
Note
The parameters to this state handler are not used. They are provided for conformance with the state-handler function signature QP::QStateHandler.
Traceability:

traces to: RQP103

traces to: RQP120T

Definition at line 185 of file qep_hsm.cpp.

◆ tran()

QState tran ( QStateHandler const  target)
inlineprotectednoexcept

Definition at line 419 of file qep.hpp.

◆ tran_hist()

QState tran_hist ( QStateHandler const  hist)
inlineprotectednoexcept

Definition at line 425 of file qep.hpp.

◆ super()

QState super ( QStateHandler const  superstate)
inlineprotectednoexcept

Definition at line 431 of file qep.hpp.

◆ qm_tran()

QState qm_tran ( void const *const  tatbl)
inlineprotectednoexcept

Definition at line 445 of file qep.hpp.

◆ qm_tran_hist()

QState qm_tran_hist ( QMState const *const  hist,
void const *const  tatbl 
)
inlineprotectednoexcept

Definition at line 452 of file qep.hpp.

◆ qm_tran_init()

QState qm_tran_init ( void const *const  tatbl)
inlineprotectednoexcept

Definition at line 462 of file qep.hpp.

◆ qm_tran_ep()

QState qm_tran_ep ( void const *const  tatbl)
inlineprotectednoexcept

Definition at line 469 of file qep.hpp.

◆ qm_tran_xp()

QState qm_tran_xp ( QActionHandler const  xp,
void const *const  tatbl 
)
inlineprotectednoexcept

Definition at line 476 of file qep.hpp.

◆ qm_entry()

QState qm_entry ( QMState const *const  s)
inlineprotectednoexcept

Definition at line 486 of file qep.hpp.

◆ qm_exit()

QState qm_exit ( QMState const *const  s)
inlineprotectednoexcept

Definition at line 492 of file qep.hpp.

◆ getStateHandler()

QStateHandler getStateHandler ( )
protectedvirtualnoexcept

Reimplemented in QMsm, and QMActive.

Definition at line 480 of file qep_hsm.cpp.

◆ qm_sm_exit()

QState qm_sm_exit ( QMState const *const  s)
inlineprotectednoexcept

Definition at line 514 of file qep.hpp.

◆ qm_super_sub()

QState qm_super_sub ( QMState const *const  s)
inlineprotectednoexcept

Definition at line 521 of file qep.hpp.

◆ hsm_tran()

std::int_fast8_t hsm_tran ( QStateHandler(&)  path[MAX_NEST_DEPTH_],
std::uint_fast8_t const  qs_id 
)
private
Description
helper function to execute transition sequence in a hierarchical state machine (HSM).
Parameters
[in,out]patharray of pointers to state-handler functions to execute the entry actions
[in]qs_idQS-id of this state machine (for QS local filter)
Returns
the depth of the entry path stored in the path parameter.
Traceability:

traces to: RQP103

traces to: RQP120E

traces to: RQP120F

Definition at line 348 of file qep_hsm.cpp.

Friends And Related Function Documentation

◆ QMsm

friend class QMsm
friend

Definition at line 548 of file qep.hpp.

◆ QActive

friend class QActive
friend

Definition at line 549 of file qep.hpp.

◆ QMActive

friend class QMActive
friend

Definition at line 550 of file qep.hpp.

◆ QF

friend class QF
friend

Definition at line 551 of file qep.hpp.

◆ QS

friend class QS
friend

Definition at line 552 of file qep.hpp.

◆ QXK

friend class QXK
friend

Definition at line 553 of file qep.hpp.

◆ QXThread

friend class QXThread
friend

Definition at line 554 of file qep.hpp.

◆ QXMutex

friend class QXMutex
friend

Definition at line 555 of file qep.hpp.

◆ QXSemaphore

friend class QXSemaphore
friend

Definition at line 556 of file qep.hpp.

◆ QHsmDummy

friend class QHsmDummy ( void  )
friend

Definition at line 558 of file qep.hpp.

◆ QActiveDummy

friend class QActiveDummy
friend

Definition at line 559 of file qep.hpp.

Member Data Documentation

◆ m_state

QHsmAttr m_state
private

Definition at line 259 of file qep.hpp.

◆ m_temp

QHsmAttr m_temp
private

Definition at line 260 of file qep.hpp.

◆ Q_RET_SUPER

constexpr QState Q_RET_SUPER {static_cast<QState>(0)}
staticconstexpr

Definition at line 379 of file qep.hpp.

◆ Q_RET_SUPER_SUB

constexpr QState Q_RET_SUPER_SUB {static_cast<QState>(1)}
staticconstexpr

Definition at line 382 of file qep.hpp.

◆ Q_RET_UNHANDLED

constexpr QState Q_RET_UNHANDLED {static_cast<QState>(2)}
staticconstexpr

Definition at line 385 of file qep.hpp.

◆ Q_RET_HANDLED

constexpr QState Q_RET_HANDLED {static_cast<QState>(3)}
staticconstexpr

Definition at line 388 of file qep.hpp.

◆ Q_RET_IGNORED

constexpr QState Q_RET_IGNORED {static_cast<QState>(4)}
staticconstexpr

Definition at line 391 of file qep.hpp.

◆ Q_RET_ENTRY

constexpr QState Q_RET_ENTRY {static_cast<QState>(5)}
staticconstexpr

Definition at line 394 of file qep.hpp.

◆ Q_RET_EXIT

constexpr QState Q_RET_EXIT {static_cast<QState>(6)}
staticconstexpr

Definition at line 397 of file qep.hpp.

◆ Q_RET_NULL

constexpr QState Q_RET_NULL {static_cast<QState>(7)}
staticconstexpr

Definition at line 400 of file qep.hpp.

◆ Q_RET_TRAN

constexpr QState Q_RET_TRAN {static_cast<QState>(8)}
staticconstexpr

Definition at line 403 of file qep.hpp.

◆ Q_RET_TRAN_INIT

constexpr QState Q_RET_TRAN_INIT {static_cast<QState>(9)}
staticconstexpr

Definition at line 406 of file qep.hpp.

◆ Q_RET_TRAN_EP

constexpr QState Q_RET_TRAN_EP {static_cast<QState>(10)}
staticconstexpr

Definition at line 409 of file qep.hpp.

◆ Q_RET_TRAN_HIST

constexpr QState Q_RET_TRAN_HIST {static_cast<QState>(11)}
staticconstexpr

Definition at line 412 of file qep.hpp.

◆ Q_RET_TRAN_XP

constexpr QState Q_RET_TRAN_XP {static_cast<QState>(12)}
staticconstexpr

Definition at line 415 of file qep.hpp.

◆ MAX_NEST_DEPTH_

constexpr std::int_fast8_t MAX_NEST_DEPTH_ {6}
staticconstexprprivate

Definition at line 528 of file qep.hpp.


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