QP/C++  5.8.2
QP::QHsm Class Reference

Hierarchical State Machine base class. More...

#include <qep.h>

Inheritance diagram for QP::QHsm:
QP::QActive QP::QMsm QP::QMActive QP::QTicker QP::QXKIdleThread QP::QXThread

Public Types

enum  ReservedHsmSignals { Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG }
 

Public Member Functions

virtual ~QHsm ()
 virtual destructor More...
 
virtual void init (QEvt const *const e)
 Executes the top-most initial transition in QP::QHsm. More...
 
virtual void init (void)
 
virtual void dispatch (QEvt const *const e)
 Dispatches an event to QHsm. More...
 
bool isIn (QStateHandler const s)
 Tests if a given state is part of the current active state configuration. More...
 
QStateHandler state (void) const
 Obtain the current state (state handler function) More...
 
QStateHandler childState (QStateHandler const parent)
 Obtain the current active child state of a given parent. More...
 
QState tran_ (QStateHandler const target)
 internal helper function to record a state transition
 
QState tran_hist_ (QStateHandler const hist)
 internal helper function to record a transition to history
 
QState super_ (QStateHandler const superstate)
 internal helper function to record the superstate
 
QState qm_tran_ (QMTranActTable const *const tatbl)
 internal helper function to record a regular state transition
 
QState qm_tran_hist_ (QMState const *const hist, QMTranActTable const *const tatbl)
 Internal helper function to record a regular state transition.
 
QState qm_tran_init_ (QMTranActTable const *const tatbl)
 Internal helper function to record an initial state transition.
 
QState qm_tran_ep_ (QMTranActTable const *const tatbl)
 Internal helper function to record an transition to an entry point to a submachine state.
 
QState qm_tran_xp_ (QActionHandler const xp, QMTranActTable const *const tatbl)
 Internal helper function to record an transition to an exit point from a submachine state.
 
QState qm_entry_ (QMState const *const s)
 Internal helper function to record a state entry.
 
QState qm_exit_ (QMState const *const s)
 Internal helper function to record a state exit.
 
QState qm_super_sub_ (QMState const *const s)
 Internal helper function to call in a QM action-handler when it passes the event to the host submachine state to handle an event.
 

Static Public Member Functions

static QState top (void *const me, QEvt const *const e)
 the top-state. More...
 
static QState Q_HANDLED (void)
 internal helper function to specify the return of a state-handler when it handles the event.
 
static QState Q_UNHANDLED (void)
 internal helper function to specify the return of a state-handler function when it attempts to handle the event but a guard condition evaluates to false and there is no other explicit way of handling the event.
 
static QState QM_HANDLED (void)
 Internal helper function to call in a QM action-handler when it handles an event.
 
static QState QM_UNHANDLED (void)
 Macro to call in a QM action-handler when it does not handle an event due to a guard condition evaluating to false.
 
static QState QM_SUPER (void)
 Internal helper function to call in a QM action-handler when it passes the event to the superstate for processing.
 

Protected Member Functions

 QHsm (QStateHandler const initial)
 Protected constructor of QHsm. More...
 

Friends

class QMsm
 
class QActive
 
class QMActive
 
class QF
 
class QXK
 
class QXThread
 
class QXMutex
 
class QXSemaphore
 

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() : QHsm(Q_STATE_CAST(&QCalc::initial)) { // ctor
}
protected:
static QState initial (Calc * const me, QEvt const *e);
static QState on (Calc * const me, QEvt const *e);
static QState error (Calc * const me, QEvt const *e);
static QState ready (Calc * const me, QEvt const *e);
static QState result (Calc * const me, QEvt const *e);
static QState begin (Calc * const me, QEvt const *e);
. . .
};

Definition at line 309 of file qep.h.

Member Enumeration Documentation

◆ ReservedHsmSignals

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 378 of file qep.h.

Constructor & Destructor Documentation

◆ ~QHsm()

QP::QHsm::~QHsm ( )
virtual

virtual destructor

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

Definition at line 125 of file qep_hsm.cpp.

◆ QHsm()

QP::QHsm::QHsm ( QStateHandler const  initial)
protected

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 116 of file qep_hsm.cpp.

Member Function Documentation

◆ childState()

QStateHandler QP::QHsm::childState ( QStateHandler const  parent)

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 581 of file qep_hsm.cpp.

◆ dispatch()

void QP::QHsm::dispatch ( QEvt const *const  e)
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
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 QP::QTicker, QP::QMsm, QP::QMActive, and QP::QXThread.

Definition at line 223 of file qep_hsm.cpp.

◆ init()

void QP::QHsm::init ( QEvt const *const  e)
virtual

Executes the top-most initial transition in QP::QHsm.

Description
Executes the top-most initial transition in a HSM.
Parameters
[in]epointer to the initialization event (might be NULL)
Note
Must be called exactly once before the QP::QHsm::dispatch().
Precondition
ctor must be executed and initial tran. NOT taken

Reimplemented in QP::QTicker, QP::QMsm, QP::QMActive, and QP::QXThread.

Definition at line 136 of file qep_hsm.cpp.

◆ isIn()

bool QP::QHsm::isIn ( QStateHandler const  s)

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]statepointer 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 540 of file qep_hsm.cpp.

◆ state()

QStateHandler QP::QHsm::state ( void  ) const
inline

Obtain the current state (state handler function)

Note
used in the QM code generation

Definition at line 333 of file qep.h.

◆ top()

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

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]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 208 of file qep_hsm.cpp.


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