qep.hpp

Go to the documentation of this file.

//============================================================================
// QP/C++ Real-Time Embedded Framework (RTEF)
// Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
//
// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
//
// This software is dual-licensed under the terms of the open source GNU
// General Public License version 3 (or any later version), or alternatively,
// under the terms of one of the closed source Quantum Leaps commercial
// licenses.
//
// The terms of the open source GNU General Public License version 3
// can be found at: <www.gnu.org/licenses/gpl-3.0>
//
// The terms of the closed source Quantum Leaps commercial licenses
// can be found at: <www.state-machine.com/licensing>
//
// Redistributions in source code must retain this top-level comment block.
// Plagiarizing this software to sidestep the license obligations is illegal.
//
// Contact information:
// <www.state-machine.com>
// <info@state-machine.com>
//============================================================================
#ifndef QEP_HPP
#define QEP_HPP
 
//============================================================================
#define QP_VERSION      701U
 
#define QP_VERSION_STR  "7.0.1"
 
#define QP_RELEASE      0x7C7E85E2U
 
//============================================================================
#ifndef Q_SIGNAL_SIZE
    #define Q_SIGNAL_SIZE 2U
#endif
 
//============================================================================
// Aliases for basic numerical types; MISRA-C++ 2008 rule 3-9-2(req).
 
using int_t = int;
 
using enum_t = int;
 
using float32_t = float;
 
using float64_t = double;
 
//============================================================================
#define Q_EVT_CAST(class_)   (static_cast<class_ const *>(e))
 
#define Q_UINT2PTR_CAST(type_, uint_)  (reinterpret_cast<type_ *>(uint_))
 
#define QEVT_INITIALIZER(sig_) { static_cast<QP::QSignal>(sig_), 0U, 0U }
 
//============================================================================
namespace QP {
 
    constexpr char const versionStr[]{QP_VERSION_STR};
 
#if (Q_SIGNAL_SIZE == 1U)
    using QSignal = std::uint8_t;
#elif (Q_SIGNAL_SIZE == 2U)
    using QSignal = std::uint16_t;
#elif (Q_SIGNAL_SIZE == 4U)
    using QSignal = std::uint32_t;
#else
    #error "Q_SIGNAL_SIZE defined incorrectly, expected 1U, 2U, or 4U"
#endif
 
#ifndef Q_EVT_CTOR // Is QEvt just a POD (Plain Old Datatype)?
 
    struct QEvt {
        QSignal sig;                   
        std::uint8_t poolId_;          
        std::uint8_t volatile refCtr_; 
    };
 
#else // QEvt is a full-blown class (not a POD)
 
    class QEvt {
    public:
        QEvt(QSignal const s) noexcept
          : sig(s)
          // poolId_/refCtr_ intentionally uninitialized
        {}
 
        enum StaticEvt : std::uint8_t { STATIC_EVT };
        constexpr QEvt(QSignal const s, StaticEvt /*dummy*/) noexcept
          : sig(s),
            poolId_(0U),
            refCtr_(0U)
        {}
 
#ifdef Q_EVT_XTOR
        virtual ~QEvt() noexcept {}
#endif // Q_EVT_XTOR
 
    public:
        QSignal sig; 
 
    private:
        std::uint8_t poolId_;          
        std::uint8_t volatile refCtr_; 
 
        friend class QF;
        friend class QS;
        friend class QActive;
        friend class QMActive;
        friend class QTimeEvt;
        friend class QEQueue;
        friend class QTicker;
        friend class QXThread;
        friend std::uint8_t QF_EVT_POOL_ID_ (QEvt const * const e) noexcept;
        friend std::uint8_t QF_EVT_REF_CTR_ (QEvt const * const e) noexcept;
        friend void QF_EVT_REF_CTR_INC_(QEvt const * const e) noexcept;
        friend void QF_EVT_REF_CTR_DEC_(QEvt const * const e) noexcept;
    };
 
#endif // Q_EVT_CTOR
 
// forward declarations...
struct QMState;
struct QMTranActTable;
class QXThread;
 
using QState = std::uint_fast8_t;
 
using QStateHandler = QState (*)(void * const me, QEvt const * const e);
 
using QActionHandler = QState (*)(void * const me);
 
using QXThreadHandler = void (*)(QXThread * const me);
 
union QHsmAttr {
    QStateHandler   fun;          
    QActionHandler  act;          
    QXThreadHandler thr;          
    QMState         const *obj;   
    QMTranActTable  const *tatbl; 
};
 
//============================================================================
class QHsm {
    QHsmAttr m_state;  
    QHsmAttr m_temp;   
 
public:
 
#ifdef Q_HSM_XTOR // provide the destructor for the QHsm and its subclasses?
    virtual ~QHsm() noexcept {}
#endif
 
    virtual void init(void const * const e,
                      std::uint_fast8_t const qs_id);
 
    virtual void init(std::uint_fast8_t const qs_id) {
        init(nullptr, qs_id);
    }
 
    virtual void dispatch(QEvt const * const e,
                          std::uint_fast8_t const qs_id);
 
    bool isIn(QStateHandler const s) noexcept;
 
    QStateHandler state(void) const noexcept {
        return m_state.fun;
    }
 
    QStateHandler childState(QStateHandler const parent) noexcept;
 
    static QState top(void * const me, QEvt const * const e) noexcept;
 
protected:
    explicit QHsm(QStateHandler const initial) noexcept;
 
public:
// facilities for the QHsm implementation strategy...
    static constexpr QState Q_RET_SUPER     {static_cast<QState>(0)};
 
    static constexpr QState Q_RET_SUPER_SUB {static_cast<QState>(1)};
 
    static constexpr QState Q_RET_UNHANDLED {static_cast<QState>(2)};
 
    static constexpr QState Q_RET_HANDLED   {static_cast<QState>(3)};
 
    static constexpr QState Q_RET_IGNORED   {static_cast<QState>(4)};
 
    static constexpr QState Q_RET_ENTRY     {static_cast<QState>(5)};
 
    static constexpr QState Q_RET_EXIT      {static_cast<QState>(6)};
 
    static constexpr QState Q_RET_NULL      {static_cast<QState>(7)};
 
    static constexpr QState Q_RET_TRAN      {static_cast<QState>(8)};
 
    static constexpr QState Q_RET_TRAN_INIT {static_cast<QState>(9)};
 
    static constexpr QState Q_RET_TRAN_EP   {static_cast<QState>(10)};
 
    static constexpr QState Q_RET_TRAN_HIST {static_cast<QState>(11)};
 
    static constexpr QState Q_RET_TRAN_XP   {static_cast<QState>(12)};
 
protected:
    QState tran(QStateHandler const target) noexcept {
        m_temp.fun = target;
        return Q_RET_TRAN;
    }
 
    QState tran_hist(QStateHandler const hist) noexcept {
        m_temp.fun = hist;
        return Q_RET_TRAN_HIST;
    }
 
    QState super(QStateHandler const superstate) noexcept {
        m_temp.fun = superstate;
        return Q_RET_SUPER;
    }
 
    enum ReservedHsmSignals : QSignal {
        Q_ENTRY_SIG = 1,     
        Q_EXIT_SIG,          
        Q_INIT_SIG           
    };
 
// protected facilities for the QMsm implementation strategy...
    QState qm_tran(void const * const tatbl) noexcept {
        m_temp.tatbl = static_cast<QP::QMTranActTable const *>(tatbl);
        return Q_RET_TRAN;
    }
 
    QState qm_tran_hist(QMState const * const hist,
                        void const * const tatbl) noexcept
    {
        m_state.obj  = hist;
        m_temp.tatbl = static_cast<QP::QMTranActTable const *>(tatbl);
        return Q_RET_TRAN_HIST;
    }
 
    QState qm_tran_init(void const * const tatbl) noexcept {
        m_temp.tatbl = static_cast<QP::QMTranActTable const *>(tatbl);
        return Q_RET_TRAN_INIT;
    }
 
    QState qm_tran_ep(void const * const tatbl) noexcept {
        m_temp.tatbl = static_cast<QP::QMTranActTable const *>(tatbl);
        return Q_RET_TRAN_EP;
    }
 
    QState qm_tran_xp(QActionHandler const xp,
                      void const *const tatbl) noexcept
    {
        m_state.act = xp;
        m_temp.tatbl = static_cast<QP::QMTranActTable const *>(tatbl);
        return Q_RET_TRAN_XP;
    }
 
#ifdef Q_SPY
    QState qm_entry(QMState const * const s) noexcept {
        m_temp.obj = s;
        return Q_RET_ENTRY;
    }
 
    QState qm_exit(QMState const * const s) noexcept {
        m_temp.obj = s;
        return Q_RET_EXIT;
    }
 
    virtual QStateHandler getStateHandler() noexcept;
#else
    QState qm_entry(QMState const * const s) noexcept {
        (void)s;
        return Q_RET_ENTRY;
    }
 
    QState qm_exit(QMState const * const s) noexcept {
        (void)s;
        return Q_RET_EXIT;
    }
#endif // Q_SPY
 
    QState qm_sm_exit(QMState const * const s) noexcept {
        m_temp.obj = s;
        return Q_RET_EXIT;
    }
 
    QState qm_super_sub(QMState const * const s) noexcept {
        m_temp.obj = s;
        return Q_RET_SUPER_SUB;
    }
 
private:
    static constexpr std::int_fast8_t MAX_NEST_DEPTH_{6};
 
    std::int_fast8_t hsm_tran(QStateHandler (&path)[MAX_NEST_DEPTH_],
                              std::uint_fast8_t const qs_id);
 
    friend class QMsm;
    friend class QActive;
    friend class QMActive;
    friend class QF;
    friend class QS;
    friend class QXK;
    friend class QXThread;
    friend class QXMutex;
    friend class QXSemaphore;
#ifdef Q_UTEST
    friend class QHsmDummy;
    friend class QActiveDummy;
#endif // Q_UTEST
};
 
//============================================================================
class QMsm : public QHsm {
public:
    void init(void const * const e,
              std::uint_fast8_t const qs_id) override;
 
    void init(std::uint_fast8_t const qs_id) override;
 
    void dispatch(QEvt const * const e,
                  std::uint_fast8_t const qs_id) override;
 
    bool isInState(QMState const * const st) const noexcept;
 
    QMState const *stateObj(void) const noexcept {
        return m_state.obj;
    }
 
    QMState const *childStateObj(QMState const * const parent) const noexcept;
 
protected:
    explicit QMsm(QStateHandler const initial) noexcept;
 
#ifdef Q_SPY
    QStateHandler getStateHandler() noexcept override;
#endif
 
private:
    bool isIn(QStateHandler const s) noexcept = delete;
 
    QStateHandler state(void) const noexcept = delete;
 
    QStateHandler childState(QStateHandler const parent) noexcept = delete;
 
    static QState top(void * const me, QEvt const * const e) noexcept = delete;
 
    QState execTatbl_(QMTranActTable const * const tatbl,
                      std::uint_fast8_t const qs_id);
 
    void exitToTranSource_(QMState const *s,
                           QMState const * const ts,
                           std::uint_fast8_t const qs_id);
 
    QState enterHistory_(QMState const * const hist,
                         std::uint_fast8_t const qs_id);
 
    static constexpr std::int_fast8_t MAX_ENTRY_DEPTH_ {4};
 
    static QMState const msm_top_s;
 
    friend class QMActive;
};
 
struct QMState {
    QMState        const *superstate;   
    QStateHandler  const stateHandler;  
    QActionHandler const entryAction;   
    QActionHandler const exitAction;    
    QActionHandler const initAction;    
};
 
struct QMTranActTable {
    QMState        const *target;
    QActionHandler const act[1];
};
 
//============================================================================
constexpr enum_t Q_USER_SIG {4};
 
} // namespace QP
 
//============================================================================
// Macros for coding QHsm-style state machines...
 
#define Q_STATE_DECL(state_)                                                 \
    QP::QState state_ ## _h(QP::QEvt const * const e);                       \
    static QP::QState state_(void * const me, QP::QEvt const * const e)
 
#define Q_STATE_DEF(subclass_, state_)                                       \
    QP::QState subclass_::state_(void * const me, QP::QEvt const * const e) {\
        return static_cast<subclass_ *>(me)->state_ ## _h(e); }              \
    QP::QState subclass_::state_ ## _h(QP::QEvt const * const e)
 
#define Q_HANDLED()           (Q_RET_HANDLED)
 
#define Q_UNHANDLED()         (Q_RET_UNHANDLED)
 
#define Q_STATE_CAST(handler_) \
    (reinterpret_cast<QP::QStateHandler>(handler_))
 
#define Q_ACTION_CAST(act_)   (reinterpret_cast<QP::QActionHandler>(act_))
 
#define Q_ACTION_NULL         (nullptr)
 
//============================================================================
// Macros for coding QMsm-style state machines...
 
#define QM_STATE_DECL(state_)                                                \
    QP::QState state_ ## _h(QP::QEvt const * const e);                       \
    static QP::QState state_(void * const me, QP::QEvt const * const e);     \
    static QP::QMState const state_ ## _s
 
#define QM_SM_STATE_DECL(subm_, state_)                                      \
    QP::QState state_ ## _h(QP::QEvt const * const e);                       \
    static QP::QState state_(void * const me, QP::QEvt const * const e);     \
    static SM_ ## subm_ const state_ ## _s
 
#define QM_ACTION_DECL(action_)                                              \
    QP::QState action_ ## _h(void);                                          \
    static QP::QState action_(void * const me)
 
#define QM_STATE_DEF(subclass_, state_)                                      \
    QP::QState subclass_::state_(void * const me, QP::QEvt const * const e) {\
        return static_cast<subclass_ *>(me)->state_ ## _h(e); }              \
    QP::QState subclass_::state_ ## _h(QP::QEvt const * const e)
 
#define QM_ACTION_DEF(subclass_, action_)                                    \
    QP::QState subclass_::action_(void * const me) {                         \
        return static_cast<subclass_ *>(me)->action_ ## _h(); }              \
    QP::QState subclass_::action_ ## _h(void)
 
#define QM_HANDLED()          (Q_RET_HANDLED)
 
#define QM_UNHANDLED()        (Q_RET_UNHANDLED)
 
#define QM_SUPER()            (Q_RET_SUPER)
 
#define QM_STATE_NULL         (nullptr)
 
#endif // QEP_HPP