QP Framework platform-independent public interface More...

Classes
class	QP::QEvt
	Event class. More...
struct	QP::QMState
	State object for the QP::QMsm class (QM State Machine). More...
struct	QP::QMTranActTable
	Transition-Action Table for the QP::QMsm State Machine. More...
union	QP::QAsmAttr
	Attribute of for the QP::QAsm class (Abstract State Machine). More...
class	QP::QAsm
	Abstract State Machine class (state machine interface). More...
class	QP::QHsm
	Hierarchical State Machine class (QHsm-style state machine implementation strategy). More...
class	QP::QMsm
	Hierarchical State Machine class (QMsm-style state machine implementation strategy). More...
class	QP::QPSet
	Set of Active Objects of up to QF_MAX_ACTIVE elements. More...
class	QP::QSubscrList
	Subscriber List (for publish-subscribe). More...
class	QP::QActive
	Active object class (based on the QP::QHsm implementation strategy). More...
class	QP::QMActive
	Active object class (based on QMsm implementation strategy). More...
class	QP::QTimeEvt
	Time Event class. More...
class	QP::QTicker
	"Ticker" Active Object class More...

Namespaces
namespace	QP
	QP/C++ Framework namespace.
namespace	QP::QF
	QF Active Object Framework namespace.

Macros
#define	QP_VERSION_STR "8.1.2"
	Version string complying with Software Versioning specification.
#define	QP_VERSION 812U
	Version number for internal use (must correspond to QP_VERSION_STR).
#define	QP_RELEASE 0x6A45C1C3U
	Encrypted current QP release for internal use (7.3.5 on 2024-05-31).
#define	Q_UNUSED_PAR(par_)
	Helper macro to clearly mark unused parameters of functions.
#define	Q_DIM(array_)
#define	Q_UINT2PTR_CAST(type_, uint_)
#define	Q_STATE_DECL(state_)
#define	Q_STATE_DEF(subclass_, state_)
#define	Q_EVT_CAST(subclass_)
	Perform downcast of an event onto a subclass of QP::QEvt class_.
#define	Q_STATE_CAST(handler_)
	Perform cast to QP::QStateHandler.
#define	QM_STATE_DECL(state_)
#define	QM_ACTION_DECL(action_)
#define	QM_STATE_DEF(subclass_, state_)
#define	QM_ACTION_DEF(subclass_, action_)
#define	INIT(qsId_)
#define	DISPATCH(e_, qsId_)
#define	Q_PRIO(prio_, pthre_)
	Create a QP::QPrioSpec object to specify priority of an AO or a thread.
#define	Q_NEW(evtT_, sig_, ...)
	Macro to allocate a dynamic event and asserting successful allocation.
#define	Q_NEW_X(evtT_, margin_, sig_, ...)
	Macro to allocate a dynamic event without asserting successful allocation.
#define	Q_NEW_REF(evtRef_, evtT_)
	Create a new reference of the current event e.
#define	Q_DELETE_REF(evtRef_)
	Delete the event reference.
#define	PUBLISH(e_, sender_)
	Publish an event to all subscriber Active Objects.
#define	POST(e_, sender_)
	Invoke the direct event posting facility QP::QActive::post_().
#define	POST_X(e_, margin_, sender_)
	Invoke the direct event posting facility QActive::postx_() without delivery guarantee.
#define	TICK_X(tickRate_, sender_)
	Invoke the system clock tick processing QP::QTimeEvt::tick_().
#define	TRIG(sender_)
	Asynchronously trigger the QP::QTicker::trig_() AO to perform tick processing.
#define	TICK(sender_)
	Invoke the system clock tick processing for tick rate 0.
#define	QF_CRIT_EXIT_NOP()
	No-operation for exiting a critical section.

Typedefs
using	int_t = int
	Alias for assertion-ID numbers in QP assertions and return from QP::QF::run().
using	QP::QSignal = std::uint16_t
	The signal of event QP::QEvt.
using	QP::QEvtPtr = QEvt const *
	Pointer to const event instances passed around in QP/C++ Framework.
using	QP::QState = std::uint_fast8_t
	Type returned from state-handler functions.
using	QP::QStateHandler = QState ()(void const me, QEvt const * const e)
	Pointer to a state-handler function.
using	QP::QActionHandler = QState ()(void const me)
	Pointer to an action-handler function.
using	QP::QXThreadHandler = void ()(QXThread const me)
	Pointer to an extended-thread handler function.
using	QP::QPrioSpec = std::uint16_t
	Priority specification for Active Objects in QP.
using	QP::QTimeEvtCtr = std::uint32_t
	Data type to store the block-size defined based on the macro QF_TIMEEVT_CTR_SIZE.
using	QP::QPSetBits = std::uint32_t
	Bitmask for the internal representation of QPSet elements.

Functions
char const *	QP::version () noexcept
std::uint_fast8_t	QP::QF_LOG2 (QP::QPSetBits const bitmask) noexcept
void	QP::QF::init ()
	QF initialization.
void	QP::QF::stop ()
	Invoked by the application layer to stop the QF framework and return control to the OS/Kernel (used in some QF ports).
int_t	QP::QF::run ()
	Transfers control to QF to run the application.
void	QP::QF::onStartup ()
	Startup QF callback.
void	QP::QF::onCleanup ()
	Cleanup QF callback.
void	QP::QF::psInit (QSubscrList *const subscrSto, QSignal const maxSignal) noexcept
void	QP::QF::publish_ (QEvt const const e, void const const sender, std::uint_fast8_t const qsId) noexcept
static std::uint_fast16_t	QP::QF::getQueueMin (std::uint_fast8_t const prio) noexcept
	This function returns the minimum of free entries of the given event queue.
void	QP::QF::tick (std::uint_fast8_t const tickRate, void const *const sender) noexcept
void	QP::QF::poolInit (void *const poolSto, std::uint_fast32_t const poolSize, std::uint_fast16_t const evtSize) noexcept
	Event pool initialization for dynamic allocation of events.
std::uint16_t	QP::QF::poolGetMaxBlockSize () noexcept
	Obtain the block size of any registered event pools.
std::uint16_t	QP::QF::getPoolUse (std::uint_fast8_t const poolNum) noexcept
std::uint16_t	QP::QF::getPoolFree (std::uint_fast8_t const poolNum) noexcept
std::uint16_t	QP::QF::getPoolMin (std::uint_fast8_t const poolNum) noexcept
	Obtain the minimum of free entries of the given event pool.
QEvt *	QP::QF::newX_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, QSignal const sig) noexcept
void	QP::QF::gc (QEvt const *const e) noexcept
	Recycle a mutable (mutable) event.
QEvt const *	QP::QF::newRef_ (QEvt const const e, QEvt const const evtRef) noexcept
void	QP::QF::deleteRef_ (QEvt const *const evtRef) noexcept
template<class evtT_, typename... Args>
evtT_ *	QP::QF::q_new (QSignal const sig, Args... args)
template<class evtT_, typename... Args>
evtT_ *	QP::QF::q_new_x (std::uint_fast16_t const margin, QSignal const sig, Args... args)
template<class evtT_>
void	QP::QF::q_new_ref (QP::QEvt const const e, evtT_ const &evtRef)
	Create a new reference of the current event e.
template<class evtT_>
void	QP::QF::q_delete_ref (evtT_ const *&evtRef)
	Delete a new reference of the current event e.
QEvt *	QP::QF::newXfromISR_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, QSignal const sig) noexcept
void	QP::QF::gcFromISR (QEvt const *e) noexcept
void	QF_onContextSw (QP::QActive prev, QP::QActive next)

Variables
constexpr QSignal	QP::Q_USER_SIG {4U}
constexpr std::uint_fast16_t	QP::QF::NO_MARGIN {0xFFFFU}
	Special value of margin that causes asserting failure in case event allocation or event posting fails.

Detailed Description

QP Framework platform-independent public interface

Forward Traceability

Definition in file qp.hpp.

Macro Definition Documentation

◆ QP_VERSION_STR

#define QP_VERSION_STR "8.1.2"

Version string complying with Software Versioning specification.

Details
QP_VERSION_STR is a zero-terminated version string in the form MAJOR.MINOR.PATCH compliant with Software Versioning specification.

Examples

7.3.5-rc.1 — version 7.3.5 release-candidate-1
7.3.5 — version 7.3.5 (final release)

Backward Traceability

SCM_SW_VER: Software Versioning

Forward Traceability

Definition at line 33 of file qp.hpp.

◆ QP_VERSION

#define QP_VERSION 812U

Version number for internal use (must correspond to QP_VERSION_STR).

Details
QP_VERSION is an unsigned integer constant of the form MAJOR|MINOR|PATCH corresponding to QP_VERSION_STR, with digits merged together. For example QP_VERSION_STR == "7.3.5-rc.1" results in QP_VERSION == 735.

Definition at line 34 of file qp.hpp.

◆ QP_RELEASE

#define QP_RELEASE 0x6A45C1C3U

Encrypted current QP release for internal use (7.3.5 on 2024-05-31).

Details
QP_RELEASE contains information about QP_VERSION (e.g., 735) and release date (e.g., 2023-06-30).

Definition at line 36 of file qp.hpp.

◆ Q_UNUSED_PAR

#define Q_UNUSED_PAR ( par_ )

Value:

(static_cast<void>(par_))

Helper macro to clearly mark unused parameters of functions.

Forward Traceability

DVR_QP_MP2_R19_0_2: Rule 19.0.2(Required): Function-like macros shall not be defined

Definition at line 89 of file qp.hpp.

◆ Q_DIM

#define Q_DIM ( array_ )

Value:

(sizeof(array_) / sizeof((array_)[0U]))

Definition at line 90 of file qp.hpp.

◆ Q_UINT2PTR_CAST

#define Q_UINT2PTR_CAST	(		type_,
			uint_ )

Value:

(reinterpret_cast<type_ *>(uint_))

Definition at line 91 of file qp.hpp.

◆ Q_STATE_DECL

#define Q_STATE_DECL ( state_ )

Value:

QP::QState state_ ## _h(QP::QEvt const * const e); \

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

QP::QEvt

Event class.

Definition qp.hpp:101

QP::QState

std::uint_fast8_t QState

Type returned from state-handler functions.

Definition qp.hpp:134

Definition at line 375 of file qp.hpp.

◆ Q_STATE_DEF

#define Q_STATE_DEF	(		subclass_,
			state_ )

Value:

    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)

Definition at line 379 of file qp.hpp.

◆ Q_EVT_CAST

#define Q_EVT_CAST ( subclass_ )

Value:

(static_cast<subclass_ const *>(e))

Perform downcast of an event onto a subclass of QP::QEvt class_.

Details
This macro encapsulates the downcast of QP::QEvt pointers, which violates MISRA-C:2025 Rule 11.3(R). This macro helps to localize this deviation.

Parameters

subclass_ a subclass of QP::QEvt

Note: The macro performs down-cast from the event pointer e.

Usage

Q_STATE_DEF(Table, serving) {
    QP::QState status_;
    switch (e->sig) {
        . . .
        case HUNGRY_SIG: {
            std::uint8_t n = Q_EVT_CAST(TableEvt)->philoId; // <===
            . . .
            break;
        }
        . . .
    }
    return status_;
}

Backward Traceability

SRS_QP_EVT_30: QP Framework shall allow Application to create event instances with Parameters defined by the Application

Forward Traceability

DVR_QP_MP2_R19_0_2: Rule 19.0.2(Required): Function-like macros shall not be defined

Definition at line 384 of file qp.hpp.

◆ Q_STATE_CAST

#define Q_STATE_CAST ( handler_ )

Value:

(reinterpret_cast<QP::QStateHandler>(handler_))

QP::QStateHandler

QState(*)(void *const me, QEvt const *const e) QStateHandler

Pointer to a state-handler function.

Definition qp.hpp:138

Perform cast to QP::QStateHandler.

Details
This macro encapsulates the cast of a specific state handler function pointer to QP::QStateHandler, which violates MISRA:C++2023 Rule 8.2.4 and Rule 8.2.5. This macro helps to localize these deviations.

Parameters

handler_ state handler (function pointer)

Usage

Philo::Philo()
  : QActive(Q_STATE_CAST(&initial)),  // <===
    m_timeEvt(this, TIMEOUT_SIG, 0U),
    m_id(0xFFU)
{}

Forward Traceability

DVP_QP_MP2_R8_2_4: Directive 8.2.4(Required): Casts shall not be performed between a pointer to function and any other type
DVP_QP_MP2_R8_2_5: Rule 8.2.5(Required): reinterpret_cast used to convert to 'QP::QStateHandler'
DVR_QP_MP2_R19_0_2: Rule 19.0.2(Required): Function-like macros shall not be defined

Definition at line 385 of file qp.hpp.

◆ QM_STATE_DECL

#define QM_STATE_DECL ( state_ )

Value:

    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

Definition at line 387 of file qp.hpp.

◆ QM_ACTION_DECL

#define QM_ACTION_DECL ( action_ )

Value:

QP::QState action_ ## _h(); \

static QP::QState action_(void * const me)

Definition at line 392 of file qp.hpp.

◆ QM_STATE_DEF

#define QM_STATE_DEF	(		subclass_,
			state_ )

Value:

    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)

Definition at line 396 of file qp.hpp.

◆ QM_ACTION_DEF

#define QM_ACTION_DEF	(		subclass_,
			action_ )

Value:

    QP::QState subclass_::action_(void * const me) { \
        return static_cast<subclass_ *>(me)->action_ ## _h(); } \
    QP::QState subclass_::action_ ## _h()

Definition at line 401 of file qp.hpp.

◆ INIT

#define INIT ( qsId_ )

Value:

init((qsId_))

Definition at line 407 of file qp.hpp.

◆ DISPATCH

#define DISPATCH	(		e_,
			qsId_ )

Value:

dispatch((e_), (qsId_))

Definition at line 408 of file qp.hpp.

◆ Q_PRIO

#define Q_PRIO	(		prio_,
			pthre_ )

Value:

(static_cast<QP::QPrioSpec>((prio_) | (pthre_) << 8U))

QP::QPrioSpec

std::uint16_t QPrioSpec

Priority specification for Active Objects in QP.

Definition qp.hpp:417

Create a QP::QPrioSpec object to specify priority of an AO or a thread.

Parameters

[in]	prio_	QF priority [1..QF_MAX_ACTIVE]
[in]	pthre_	Preemption threshold [1..QF_MAX_ACTIVE]

Returns: The combined 16-bit priority specification (prio_ in bits [0..7] and pthre_ in bits [8..15].

Definition at line 893 of file qp.hpp.

◆ Q_NEW

#define Q_NEW	(	evtT_,
		sig_,
		... )

Value:

(QP::QF::q_new<evtT_>((sig_), __VA_ARGS__))

QP::QF::q_new

evtT_ * q_new(QSignal const sig, Args... args)

Definition qp.hpp:829

Macro to allocate a dynamic event and asserting successful allocation.

Details
This deprecated macro is equivalent to invoking the function template QP::QF::q_new<evtT_>(sig_, ...).

Deprecated

See also: QP::QF::q_new()

Parameters

[in]	evtT_	event type (class name) of the event to allocate
[in]	sig_	signal to assign to the newly allocated event

Returns: A valid event pointer of the type evtT_*.

Definition at line 901 of file qp.hpp.

◆ Q_NEW_X

#define Q_NEW_X	(	evtT_,
		margin_,
		sig_,
		... )

Value:

(QP::QF::q_new_x<evtT_>((margin_), (sig_), __VA_ARGS__))

QP::QF::q_new_x

evtT_ * q_new_x(std::uint_fast16_t const margin, QSignal const sig, Args... args)

Definition qp.hpp:838

Macro to allocate a dynamic event without asserting successful allocation.

Details
This deprecated macro is equivalent to invoking the function template QP::QF::q_new_x<evtT_>(margin_, sig_, ...).

Deprecated

See also: QP::QF::q_new_x()

Parameters

[in]	evtT_	event type (class name) of the event to allocate
[in]	margin_	number of events that must remain available in the given pool after this allocation. The special value ::QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]	sig_	signal to assign to the newly allocated event

Returns: An event pointer of the type evtT_* or nullptr if the event cannot be allocated with the specified margin_ of events still left in the event pool.

Definition at line 903 of file qp.hpp.

◆ Q_NEW_REF

#define Q_NEW_REF	(		evtRef_,
			evtT_ )

Value:

(QP::QF::q_new_ref<evtT_>(e, (evtRef_)))

QP::QF::q_new_ref

void q_new_ref(QP::QEvt const *const e, evtT_ const *&evtRef)

Create a new reference of the current event e.

Definition qp.hpp:854

Create a new reference of the current event e.

Details
This deprecated macro is equivalent to invoking the function template QP::QF::q_new_ref<evtT_>(e, evtRef).

Deprecated

See also: QP::QF::q_new_ref()

Parameters

[in,out]	evtRef_	event reference to create
[in]	evtT_	event type (class name) of the event reference

Definition at line 907 of file qp.hpp.

◆ Q_DELETE_REF

#define Q_DELETE_REF ( evtRef_ )

Value:

    do { \
    QP::QF::deleteRef_((evtRef_)); \
    (evtRef_) = nullptr; \
} while (false)

Delete the event reference.

Details
This deprecated macro is equivalent to invoking the function template QP::QF::q_new_ref<evtT_>(e, evtRef).

Deprecated

See also: QP::QF::q_delete_ref()

Parameters

[in,out] evtRef_ event reference to delete

Definition at line 908 of file qp.hpp.

◆ PUBLISH

#define PUBLISH	(		e_,
			sender_ )

Value:

publish_((e_), (sender_), (sender_)->getPrio())

Publish an event to all subscriber Active Objects.

Details
If Q_SPY is defined, this macro calls QP::QActive::publish_() with the sender_ parameter to identify the publisher of the event. Otherwise, sender_ is not used.

Parameters

[in]	e_	pointer to the posted event
[in]	sender_	pointer to the sender object (actually used only when Q_SPY is defined)

Note: The pointer to the sender_ object is not necessarily a pointer to an active object. In fact, if QACTIVE_PUBLISH() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

Definition at line 914 of file qp.hpp.

◆ POST

#define POST	(		e_,
			sender_ )

Value:

post_((e_), (sender_))

Invoke the direct event posting facility QP::QActive::post_().

Details
This macro asserts if the queue overflows and cannot accept the event.

Parameters

[in]	e_	pointer to the event to post
[in]	sender_	pointer to the sender object.

Note: The sender_ parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, this macro does not use the sender_ parameter, so it does not need to be defined.

See also

QP::QActive::post_()

Definition at line 916 of file qp.hpp.

◆ POST_X

#define POST_X	(	e_,
		margin_,
		sender_ )

Value:

postx_((e_), (margin_), (sender_))

Invoke the direct event posting facility QActive::postx_() without delivery guarantee.

Details
This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.

Parameters

[in]	e_	pointer to the event to post
[in]	margin_	the minimum free slots in the queue, which must still be available after posting the event. The special value QF::NO_MARGIN causes asserting failure in case event posting fails.
[in]	sender_	pointer to the sender object.

Returns: 'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free entries available in the queue.

Note: The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the POST_X() macro does not pass the sender_ parameter, so the overhead of passing this extra parameter is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, if POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

Backward Traceability

Definition at line 917 of file qp.hpp.

◆ TICK_X

#define TICK_X	(		tickRate_,
			sender_ )

Value:

tick((tickRate_), (sender_))

Invoke the system clock tick processing QP::QTimeEvt::tick_().

Details
This macro is the recommended way of invoking clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

Parameters

[in]	tickRate_	clock tick rate to be serviced through this call
[in]	sender_	pointer to the sender object. This parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: When QS software tracing is disabled, the macro calls QTimeEvt::tick_() without the sender parameter, so the overhead of passing this extra parameter is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, when TICK_X() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.

Definition at line 919 of file qp.hpp.

◆ TRIG

#define TRIG ( sender_ )

Value:

trig_((sender_))

Asynchronously trigger the QP::QTicker::trig_() AO to perform tick processing.

Details
This macro is the recommended way to trigger clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

Parameters

[in] sender_ pointer to the sender object. This parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: When QS software tracing is disabled, the macro calls QTicker_trig_() without the sender parameter, so the overhead of passing this extra parameter is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, when QTICKER_TRIG() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.

Definition at line 920 of file qp.hpp.

◆ TICK

#define TICK ( sender_ )

Value:

TICK_X(0U, (sender_))

TICK_X

#define TICK_X(tickRate_, sender_)

Invoke the system clock tick processing QP::QTimeEvt::tick_().

Definition qp.hpp:919

Invoke the system clock tick processing for tick rate 0.

Parameters

[in] sender_ pointer to the sender object. This parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined)

Definition at line 929 of file qp.hpp.

◆ QF_CRIT_EXIT_NOP

#define QF_CRIT_EXIT_NOP ( )

Value:

(static_cast<void>(0))

No-operation for exiting a critical section.

Details
In some QF ports the critical section exit takes effect only on the next machine instruction. If this next instruction is another entry to a critical section, the critical section won't be really exited, but rather the two adjacent critical sections would be merged. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in such merging of critical sections in QF ports, in which it can occur.

Definition at line 932 of file qp.hpp.

Typedef Documentation

◆ int_t

using int_t = int

Alias for assertion-ID numbers in QP assertions and return from QP::QF::run().

Definition at line 87 of file qp.hpp.

Function Documentation

◆ QF_onContextSw()

void QF_onContextSw	(	QP::QActive *	prev,
		QP::QActive *	next )

Classes

Namespaces

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ QP_VERSION_STR

◆ QP_VERSION

◆ QP_RELEASE

◆ Q_UNUSED_PAR

◆ Q_DIM

◆ Q_UINT2PTR_CAST

◆ Q_STATE_DECL

◆ Q_STATE_DEF

◆ Q_EVT_CAST

◆ Q_STATE_CAST

◆ QM_STATE_DECL

◆ QM_ACTION_DECL

◆ QM_STATE_DEF

◆ QM_ACTION_DEF

◆ INIT

◆ DISPATCH

◆ Q_PRIO

◆ Q_NEW

◆ Q_NEW_X

◆ Q_NEW_REF

◆ Q_DELETE_REF

◆ PUBLISH

◆ POST

◆ POST_X

◆ TICK_X

◆ TRIG

◆ TICK

◆ QF_CRIT_EXIT_NOP

Typedef Documentation

◆ int_t

Function Documentation

◆ QF_onContextSw()