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

#include <qep.hpp>

Inheritance diagram for QHsm:
Inheritance graph
Collaboration diagram for QHsm:
Collaboration graph

Public Member Functions

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
 
QStateHandler state (void) const noexcept
 
QStateHandler childState (QStateHandler const parent) noexcept
 

Static Public Member Functions

static QState top (void *const me, QEvt const *const e) noexcept
 the top-state. 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
 
QState qm_tran_hist (QMState const *const hist, void const *const tatbl) noexcept
 
QState qm_tran_init (void const *const tatbl) noexcept
 
QState qm_tran_ep (void const *const tatbl) noexcept
 
QState qm_tran_xp (QActionHandler const xp, void const *const tatbl) noexcept
 
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
 

Private Member Functions

std::int_fast8_t hsm_tran (QStateHandler(&path)[MAX_NEST_DEPTH_], std::uint_fast8_t const qs_id)
 internal 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 QActiveDummy
 

Detailed Description

Hierarchical State Machine base class

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 inherits QMsm without adding new attributes, so it takes the same amount of RAM as QMsm.
QHsm is also the base class for the QMsm state machine, which provides a superior efficiency, but requries 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 QHsm { // derived from QHsm
private:
double m_operand1;
double m_operand2;
char m_display[DISP_WIDTH + 1];
uint8_t m_len;
uint8_t m_opKey;
public:
Calc() // constructor
: 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);
. . .
};
unsigned char uint8_t
Definition: 16bit/stdint.h:29
QHsm(QStateHandler const initial) noexcept
Protected constructor of QHsm.
Definition: qep_hsm.cpp:117
#define Q_STATE_DECL(state_)
Definition: qep.hpp:619

Definition at line 269 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 371 of file qep.hpp.

Constructor & Destructor Documentation

◆ ~QHsm()

~QHsm ( )
virtual

virtual destructor

Description
Virtual destructor of the QHsm state machine and any of its subclasses.

Definition at line 126 of file qep_hsm.cpp.

◆ QHsm()

QHsm ( QStateHandler const  initial)
explicitprotectednoexcept

Protected constructor of QHsm.

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

Definition at line 117 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

executes the top-most initial transition in QP::QHsm

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().
Precondition
ctor must have been executed and initial tran NOT taken

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

Definition at line 139 of file qep_hsm.cpp.

◆ init() [2/2]

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

overloaded init(qs_id)

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

Definition at line 282 of file qep.hpp.

◆ dispatch()

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

Dispatches an event to QHsm.

Description
Dispatches an event for processing to a hierarchical state machine (HSM). 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().
Precondition
the current state must be initialized and the state configuration must be stable

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

Definition at line 242 of file qep_hsm.cpp.

◆ isIn()

bool isIn ( QStateHandler const  s)
noexcept

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

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
Precondition
state configuration must be stable

Definition at line 557 of file qep_hsm.cpp.

◆ state()

QStateHandler state ( void  ) const
inlinenoexcept

Obtain the current state (state handler function)

Note
used in the QM code generation

Definition at line 296 of file qep.hpp.

◆ childState()

QStateHandler childState ( QStateHandler const  parent)
noexcept

Obtain the current active child state of a given parent

Note
used in the QM code generation
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 QHsm.
Parameters
[in]parentpointer to the state-handler function
Returns
the child of a given parent state, which is an ancestor of the currently active state
Note
this function is designed to be called during state transitions, so it does not necessarily start in a stable state configuration. However, the function establishes stable state configuration upon exit.
Postcondition
the child must be confirmed

Definition at line 600 of file qep_hsm.cpp.

◆ top()

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

the top-state.

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 arguments to this state handler are not used. They are provided for conformance with the state-handler function signature QP::QStateHandler.

Definition at line 224 of file qep_hsm.cpp.

◆ tran()

QState tran ( QStateHandler const  target)
inlineprotectednoexcept

Helper function to specify a state transition.

Definition at line 354 of file qep.hpp.

◆ tran_hist()

QState tran_hist ( QStateHandler const  hist)
inlineprotectednoexcept

Helper function to specify a transition to history.

Definition at line 360 of file qep.hpp.

◆ super()

QState super ( QStateHandler const  superstate)
inlineprotectednoexcept

Helper function to specify the superstate of a given state.

Definition at line 366 of file qep.hpp.

◆ qm_tran()

QState qm_tran ( void const *const  tatbl)
inlineprotectednoexcept

Helper function to specify a regular state transition in a QM state-handler

Definition at line 380 of file qep.hpp.

◆ qm_tran_hist()

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

Helper function to specifiy a transition to history in a QM state-handler

Definition at line 387 of file qep.hpp.

◆ qm_tran_init()

QState qm_tran_init ( void const *const  tatbl)
inlineprotectednoexcept

Helper function to specify an initial state transition in a QM state-handler

Definition at line 397 of file qep.hpp.

◆ qm_tran_ep()

QState qm_tran_ep ( void const *const  tatbl)
inlineprotectednoexcept

Helper function to specify a transition to an entry point to a submachine state in a QM state-handler

Definition at line 404 of file qep.hpp.

◆ qm_tran_xp()

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

Helper function to specify a transition to an exit point from a submachine state in a QM state-handler

Definition at line 411 of file qep.hpp.

◆ qm_entry()

QState qm_entry ( QMState const *const  s)
inlineprotectednoexcept

Helper function to specify a state entry in a QM state-handler.

Definition at line 421 of file qep.hpp.

◆ qm_exit()

QState qm_exit ( QMState const *const  s)
inlineprotectednoexcept

Helper function to specify a state exit in a QM state-handler.

Definition at line 427 of file qep.hpp.

◆ getStateHandler()

QStateHandler getStateHandler ( )
protectedvirtualnoexcept

Get the current state handler of the HSM.

Reimplemented in QMActive, and QMsm.

Definition at line 539 of file qep_hsm.cpp.

◆ qm_sm_exit()

QState qm_sm_exit ( QMState const *const  s)
inlineprotectednoexcept

Helper function to specify a submachine exit in a QM state-handler.

Definition at line 449 of file qep.hpp.

◆ qm_super_sub()

QState qm_super_sub ( QMState const *const  s)
inlineprotectednoexcept

Helper function to call in a QM state-handler when it passes the event to the host submachine state to handle an event.

Definition at line 456 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

internal helper function to take a transition in QP::QHsm

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.

Definition at line 404 of file qep_hsm.cpp.

Friends And Related Function Documentation

◆ QMsm

friend class QMsm
friend

Definition at line 469 of file qep.hpp.

◆ QActive

friend class QActive
friend

Definition at line 470 of file qep.hpp.

◆ QMActive

friend class QMActive
friend

Definition at line 471 of file qep.hpp.

◆ QF

friend class QF
friend

Definition at line 472 of file qep.hpp.

◆ QS

friend class QS
friend

Definition at line 473 of file qep.hpp.

◆ QXK

friend class QXK
friend

Definition at line 474 of file qep.hpp.

◆ QXThread

friend class QXThread
friend

Definition at line 475 of file qep.hpp.

◆ QXMutex

friend class QXMutex
friend

Definition at line 476 of file qep.hpp.

◆ QXSemaphore

friend class QXSemaphore
friend

Definition at line 477 of file qep.hpp.

◆ QActiveDummy

friend class QActiveDummy
friend

Definition at line 479 of file qep.hpp.

Field Documentation

◆ m_state

QHsmAttr m_state
private

current active state (state-variable)

Definition at line 270 of file qep.hpp.

◆ m_temp

QHsmAttr m_temp
private

temporary: transition chain, target state, etc.

Definition at line 271 of file qep.hpp.

◆ Q_RET_SUPER

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

event passed to the superstate to handle

Definition at line 314 of file qep.hpp.

◆ Q_RET_SUPER_SUB

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

event passed to submachine superstate

Definition at line 317 of file qep.hpp.

◆ Q_RET_UNHANDLED

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

event unhandled due to a guard evaluating to 'false'

Definition at line 320 of file qep.hpp.

◆ Q_RET_HANDLED

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

event handled (internal transition)

Definition at line 323 of file qep.hpp.

◆ Q_RET_IGNORED

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

event silently ignored (bubbled up to top)

Definition at line 326 of file qep.hpp.

◆ Q_RET_ENTRY

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

state entry action executed

Definition at line 329 of file qep.hpp.

◆ Q_RET_EXIT

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

state exit action executed

Definition at line 332 of file qep.hpp.

◆ Q_RET_NULL

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

return value without any effect

Definition at line 335 of file qep.hpp.

◆ Q_RET_TRAN

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

regular transition taken

Definition at line 338 of file qep.hpp.

◆ Q_RET_TRAN_INIT

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

initial transition taken

Definition at line 341 of file qep.hpp.

◆ Q_RET_TRAN_EP

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

entry-point transition into a submachine

Definition at line 344 of file qep.hpp.

◆ Q_RET_TRAN_HIST

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

transition to history of a given state

Definition at line 347 of file qep.hpp.

◆ Q_RET_TRAN_XP

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

exit-point transition out of a submachine

Definition at line 350 of file qep.hpp.

◆ MAX_NEST_DEPTH_

constexpr std::int_fast8_t MAX_NEST_DEPTH_ {6}
staticconstexprprivate

< maximum nesting depth of states in HSM

Definition at line 463 of file qep.hpp.


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