Hierarchical State Machine base class. More...

#include <qep.h>

Public Member Functions
virtual	~QHsm ()
	virtual destructor
void	init (QEvt const const e=static_cast< QEvt const >(0))
	Performs the second step of HSM initialization by triggering the top-most initial transition.
void	dispatch (QEvt const *const e)
	Dispatches an event to a HSM.
bool	isIn (QStateHandler const s)
	Tests if a given state is part of the current active state configuration.
Protected Types
enum	ReservedHsmSignals { Q_ENTRY_SIG = 1, Q_EXIT_SIG, Q_INIT_SIG }
Protected Member Functions
	QHsm (QStateHandler const initial)
	Protected constructor of a HSM.
QStateHandler	state (void) const
	Return the current active state.
QState	tran (QStateHandler const target)
	internal helper function to record a state transition
QState	super (QStateHandler const superstate)
	internal helper function to record the superstate
Static Protected Member Functions
static QState	top (void const me, QEvt const const e)
	the top-state.
static QState	Q_HANDLED (void)
	Inline function to specify the return of a state-handler when it handles the event.
static QState	Q_UNHANDLED (void)
	Macro 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.

Detailed Description

Hierarchical State Machine base class.

QHsm represents a Hierarchical Finite State Machine (HSM). QHsm derives from the QFsm class and extends the capabilities of a basic FSM with state hierarchy.

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

The following example illustrates how to derive a state machine class from QHsm.

class QCalc : public QHsm {                // Quantum Calculator state machine
private:
    double  m_operand1;
    double  m_operand2;
    char    m_display[DISP_WIDTH + 1];
    uint8_t m_len;
    uint8_t m_opKey;

public:
    QCalc() : QHsm((QStateHandler)&QCalc::initial) {                   // ctor
    }

protected:
    static QState initial  (QCalc *me, QEvent const *e);
    static QState on       (QCalc *me, QEvent const *e);
    static QState error    (QCalc *me, QEvent const *e);
    static QState ready    (QCalc *me, QEvent const *e);
    static QState result   (QCalc *me, QEvent const *e);
    static QState begin    (QCalc *me, QEvent const *e);
    static QState negated1 (QCalc *me, QEvent const *e);
    static QState operand1 (QCalc *me, QEvent const *e);
    static QState zero1    (QCalc *me, QEvent const *e);
    static QState int1     (QCalc *me, QEvent const *e);
    static QState frac1    (QCalc *me, QEvent const *e);
    static QState opEntered(QCalc *me, QEvent const *e);
    static QState negated2 (QCalc *me, QEvent const *e);
    static QState operand2 (QCalc *me, QEvent const *e);
    static QState zero2    (QCalc *me, QEvent const *e);
    static QState int2     (QCalc *me, QEvent const *e);
    static QState frac2    (QCalc *me, QEvent const *e);
};

Definition at line 236 of file qep.h.

Member Enumeration Documentation

enum QHsm::ReservedHsmSignals [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 329 of file qep.h.

Constructor & Destructor Documentation

QHsm::QHsm ( QStateHandler const initial ) [inline, protected]

Protected constructor of a HSM.

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

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

See also:: The QHsm example illustrates how to use the QHsm constructor in the constructor initializer list of the derived state machines.; QFsm::QFsm()

Definition at line 287 of file qep.h.

Member Function Documentation

QP_BEGIN_ void QHsm::dispatch ( QEvt const *const e )

Dispatches an event to a HSM.

Processes one event at a time in Run-to-Completion (RTC) fashion. The argument e is a constant pointer the ::QEvt or a class derived from ::QEvt.

Note:: Must be called after QHsm::init().

See also:: example for QHsm::init()

Definition at line 47 of file qhsm_dis.cpp.

References Q_ASSERT, Q_REQUIRE, Q_RET_HANDLED, Q_RET_IGNORED, Q_RET_SUPER, Q_RET_TRAN, Q_RET_UNHANDLED, QEP_EMPTY_SIG_, QEP_ENTER_, QEP_EXIT_, QEP_MAX_NEST_DEPTH_, QEP_TRIG_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_DISPATCH, QS_QEP_IGNORED, QS_QEP_INTERN_TRAN, QS_QEP_STATE_EXIT, QS_QEP_STATE_INIT, QS_QEP_TRAN, QS_QEP_UNHANDLED, QS_TIME_, s8_0, s8_1, s8_n1, and QS::smObj_.

void QHsm::init ( QEvt const *const e = static_cast<QEvt const *>(0) )

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

Parameters:

e	constant pointer ::QEvt or a class derived from ::QEvt

Note:: Must be called only ONCE before QHsm::dispatch()

The following example illustrates how to initialize a HSM, and dispatch events to it:

#include "qep.h"                                     // QEP/C public interface
#include "qcalc.h"                              // QCalc HSM derived from QHsm

static QCalc l_qcalc;                              // an instance of QCalc HSM

int main() {

    l_qcalc.init();                              // trigger initial transition

    for (;;) {                                                   // event loop
        QEvent e;
        . . .
        // wait for the next event and assign it to the event object e
        . . .
        l_qcalc.dispatch(&e);                            // dispatch the event
    }
    return 0;
}

Definition at line 50 of file qhsm_ini.cpp.

References Q_ALLEGE, Q_ASSERT, Q_INIT_SIG, Q_REQUIRE, Q_RET_TRAN, Q_STATE_CAST, QEP_EMPTY_SIG_, QEP_ENTER_, QEP_MAX_NEST_DEPTH_, QEP_TRIG_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_INIT_TRAN, QS_QEP_STATE_INIT, QS_TIME_, s8_0, QS::smObj_, and top().

QP_BEGIN_ bool QHsm::isIn ( QStateHandler const s )

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

Parameters:

state is a pointer to the state handler function, e.g., &QCalc::on.

Definition at line 47 of file qhsm_in.cpp.

References Q_REQUIRE, Q_RET_IGNORED, QEP_EMPTY_SIG_, and QEP_TRIG_.

static QState QHsm::Q_HANDLED ( void ) [inline, static, protected]

Inline function to specify the return of a state-handler when it handles the event.

class QCalc : public QHsm {                // Quantum Calculator state machine
private:
    double  m_operand1;
    double  m_operand2;
    char    m_display[DISP_WIDTH + 1];
    uint8_t m_len;
    uint8_t m_opKey;

public:
    QCalc() : QHsm((QStateHandler)&QCalc::initial) {                   // ctor
    }

protected:
    static QState initial  (QCalc *me, QEvent const *e);
    static QState on       (QCalc *me, QEvent const *e);
    static QState error    (QCalc *me, QEvent const *e);
    static QState ready    (QCalc *me, QEvent const *e);
    static QState result   (QCalc *me, QEvent const *e);
    static QState begin    (QCalc *me, QEvent const *e);
    static QState negated1 (QCalc *me, QEvent const *e);
    static QState operand1 (QCalc *me, QEvent const *e);
    static QState zero1    (QCalc *me, QEvent const *e);
    static QState int1     (QCalc *me, QEvent const *e);
    static QState frac1    (QCalc *me, QEvent const *e);
    static QState opEntered(QCalc *me, QEvent const *e);
    static QState negated2 (QCalc *me, QEvent const *e);
    static QState operand2 (QCalc *me, QEvent const *e);
    static QState zero2    (QCalc *me, QEvent const *e);
    static QState int2     (QCalc *me, QEvent const *e);
    static QState frac2    (QCalc *me, QEvent const *e);
};

Definition at line 310 of file qep.h.

References Q_RET_HANDLED.

QP_BEGIN_ QState QHsm::top	(	void *const	me,
		QEvt const *const	e
	)		`[static, protected]`

the top-state.

QHsm::top() is the ultimate root of state hierarchy in all HSMs derived from QHsm. This state handler always returns (QSTATE)0, which means that it "handles" all events.

See also:: Example of the QCalc::on() state handler.

Definition at line 44 of file qhsm_top.cpp.

References Q_RET_IGNORED.

Referenced by init().

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

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation