QFsm Class Reference

Finite State Machine base class. More...

#include <qep.h>

List of all members.

Public Member Functions
virtual	~QFsm ()
	virtual destructor
void	init (QEvt const *const e=static_cast< QEvt const * >(0))
	Performs the second step of FSM initialization by triggering the top-most initial transition.
void	dispatch (QEvt const *const e)
	Dispatches an event to a FSM.
Protected Types
enum	ReservedFsmSignals { Q_ENTRY_SIG = 1, Q_EXIT_SIG }
Protected Member Functions
	QFsm (QStateHandler const initial)
	Protected constructor of a FSM.
QStateHandler	state (void) const
	Return the current active state.
QState	tran (QStateHandler const target)
	internal helper function to record a state transition
Static Protected Member Functions
static QState	Q_IGNORED (void)
	Inline function to specify the return of a state-handler when it igonres (does not handle in any way) the event.
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

Finite State Machine base class.

QFsm represents a traditional non-hierarchical Finite State Machine (FSM) without state hierarchy, but with entry/exit actions.

QFsm is also a base structure for the QHsm class.

Note:

QFsm is not intended to be instantiated directly, but rather serves as the base class for derivation of state machines in the application code.

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

class QBomb : public QFsm {
    uint8_t m_timeout;                     // number of seconds till explosion
    uint8_t m_defuse;                                // the secret defuse code
    uint8_t m_code;                           // the current defuse code entry

public:
    QBomb() : QFsm((QStateHandler)&QBomb::initial) {
    }

protected:
    static QState initial(QBomb *me, QEvent const *e);
    static QState setting(QBomb *me, QEvent const *e);
    static QState timing(QBomb *me, QEvent const *e);
    static QState blast(QBomb *me, QEvent const *e);
};

Definition at line 140 of file qep.h.

---

Member Enumeration Documentation

enum QFsm::ReservedFsmSignals [protected]

Enumerator:

Q_ENTRY_SIG	signal for entry actions
Q_EXIT_SIG	signal for exit actions

Definition at line 216 of file qep.h.

---

Constructor & Destructor Documentation

QFsm::QFsm

(

QStateHandler const

initial

)

[inline, protected]

Protected constructor of a FSM.

Performs the first step of FSM 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 QFsm objects. This class is intended for subclassing only.

See also:

The QFsm example illustrates how to use the QHsm constructor in the constructor initializer list of the derived state machines.

Definition at line 185 of file qep.h.

---

Member Function Documentation

QP_BEGIN_ void QFsm::dispatch

(

QEvt const *const

e

)

Dispatches an event to a FSM.

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 QFsm::init().

See also:

example for QFsm::init()

Definition at line 47 of file qfsm_dis.cpp.

References Q_REQUIRE, Q_RET_HANDLED, Q_RET_TRAN, Q_RET_UNHANDLED, QEP_ENTER_, QEP_EXIT_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_DISPATCH, QS_QEP_IGNORED, QS_QEP_INTERN_TRAN, QS_QEP_TRAN, QS_QEP_UNHANDLED, QS_TIME_, and QS::smObj_.

void QFsm::init

(

QEvt const *const

e = static_cast<QEvt const *>(0)

)

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

The argument e is constant pointer to ::QEvt or a class derived from ::QEvt.

Note:

Must be called only ONCE before QFsm::dispatch()

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

#include "qep.h"                                     // QEP/C public interface
#include "qbomb.h"                              // QBomb FSM derived from QFsm

static QBomb l_qbomb;                              // an instance of QBomb FSM

int main() {
    QBombInitEvt ie;
    ie.defuse = 0x0D;                                           // 1101 binary
    l_qbomb.init(&ie);                           // trigger initial transition

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

Definition at line 50 of file qfsm_ini.cpp.

References Q_ALLEGE, Q_ENTRY_SIG, Q_REQUIRE, Q_RET_TRAN, Q_STATE_CAST, QEP_TRIG_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_FUN_, QS_OBJ_, QS_QEP_INIT_TRAN, QS_QEP_STATE_INIT, QS_TIME_, and QS::smObj_.

static QState QFsm::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 203 of file qep.h.

References Q_RET_HANDLED.

---

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

• qep.h
• qfsm_dis.cpp
• qfsm_ini.cpp