QP::QEvt Class Reference

Event class. More...

#include <qp.hpp>

Inheritance diagram for QP::QEvt:

Public Types
enum	DynEvt : std::uint8_t { DYNAMIC }

Public Member Functions
constexpr	QEvt (QSignal const s) noexcept
	Event constexpr constructor applicable to immutable and mutable event instances.
	QEvt ()=delete
	Disallowed default event constructor.
void	init () const noexcept
	Event initialization for dynamic events.
void	init (DynEvt const dummy) const noexcept
	Event initialization for dynamic events (overload).

Public Attributes
std::uint32_t	sig: 16
	Signal of the event (see Event Signal).
std::uint32_t	poolNum_: 8
	Event pool number of this event.
std::uint32_t	refCtr_: 8
	Event reference counter.
std::uint32_t	filler_
	Member of QP::QEvt to make it identical size in QP/C++ and SafeQP/C++.

Detailed Description

Event class.

Details
Class QP::QEvt represents both immutable and mutable QP events. It can be instantiated directly (concrete class), in which case it represents events without parameters. QP/C++ Applications can also inherit and extend QP::QEvt to add custom event parameters (see also SDS_QP_QEvt).

Usage
The following example illustrates how to add event parameter(s) by inheriting the QP::QEvt class. Please note that the QEvt member super is defined as the FIRST member of the derived class.

struct KeypressEvt : public QP::QEvt { // <=== inherit QP::QEvt
    // event parameters follow...
    std::uint8_t keyId; // ID of the key pressed
};

The following examples illustrate recommended ways to instantiate event objects based on the RAII principle (Resource Acquisition Is Initialization). Please see also QP::QEvt::QEvt().

// immutable event without parameters
static QP::QEvt const myEvt { MY_SIG };
// post, publish, or dispatch the immutable event...
 
// immutable event with parameters
static KeypressEvt const keyEvt {
    QP::QEvt(KEYPRESS_SIG), // inherited part
    12U           // .keyId attribute
}
// post, publish, or dispatch the immutable event...
 
// mutable event without parameters (e.g., automatic object inside a function)
QP::QEvt myEvt { sig }; // sig is a variable
// dispatch the event (asynchronous posting or publishing probably WRONG!)
 
// mutable event with parameters (e.g., automatic object inside a function)
KeypressEvt keyEvt { // sig and keyId are variables
    QP::QEvt(sig),  // inherited part
    keyId // .keyId attribute
};
// dispatch the event (asynchronous posting or publishing probably WRONG!)

Attention

Event parameters must be included in the event instance directly (as opposed to being referenced by pointers or references). Therefore, the subclasses of QP::QEvt are restricted to have both "standard layout" and be "trivially copyable". In QP/C++ this means that QP::QEvt subclasses should:

• contain NO pointers (including NO virtual pointer). The only exception is passing an opaque pointer to Active Object intended as the recipient of future events.
• contain NO virtual functions (consequence of no virtual pointer);
• contain NO access specifiers (protected, and private);
• contain NO non-trivial copy or move constructor;
• contain NO non-trivial copy or move assignment operator;
• contain NO destructor.

Note

Please see QP::QEvt::QEvt(QSignal) for examples of instantiating event objects (immutable and mutable on the stack). Please see QP::QF::q_new()/QP::QF::q_new_x() for code examples of allocating dynamic mutable events.

Backward Traceability

• SDS_QP_QEvt: QEvt event class.

Forward Traceability

• DVP_QP_PCLP_1790: public base has no non-destructor virtual functions
• DVR_QP_PCLP_1801: Base class has a destructor that is not public virtual; public override or protected non-virtual
• QSignal: The signal of event QP::QEvt

Definition at line 101 of file qp.hpp.

Member Enumeration Documentation

DynEvt

enum QP::QEvt::DynEvt : std::uint8_t

Enumerator
DYNAMIC	Dummy parameter for dynamic event initialization (see QEvt::QEvt(DynEvt)). Forward Traceability

Definition at line 108 of file qp.hpp.

Constructor & Destructor Documentation

QEvt() [1/2]

QP::QEvt::QEvt ( QSignal const s )

inlineexplicitconstexprnoexcept

Event constexpr constructor applicable to immutable and mutable event instances.

Parameters

[in]

s

signal of the event to initialize (for non-dynamic events)

Usage
The following examples illustrate recommended ways to use the QEvt(QSignal) constructor to instantiate event objects based on the RAII principle (Resource Acquisition Is Initialization).

// immutable event without parameters
static QP::QEvt const myEvt { APP::MY_SIG }; // <== use constexpr QEvt ctor
// post, publish, or dispatch the immutable event...
 
// immutable event with parameters
static APP::KeypressEvt const keyEvt { APP::KEYPRESS_SIG, 12U };
// post, publish, or dispatch the immutable event...
 
// array of immutable events with parameters
static APP::KeypressEvt const keyboardEvt[] {
    { APP::KEYPRESS_SIG, 12U },
    { APP::KEYPRESS_SIG, 13U }
};
 
// mutable event without parameters (e.g., automatic object inside a function)
QP::QEvt myEvt { sig }; // sig is a variable
// dispatch the event (asynchronous posting or publishing probably WRONG!)
 
// mutable event with parameters (e.g., automatic object inside a function)
APP::KeypressEvt keyEvt { sig, keyId };
// dispatch the event (asynchronous posting or publishing probably WRONG!)

Forward Traceability

Definition at line 110 of file qp.hpp.

QEvt() [2/2]

QP::QEvt::QEvt ( )

delete

Disallowed default event constructor.

Details
The default event constructor is explicitly disallowed (= delete), so that all subclasses of QP::QEvt must provide constructors.

Forward Traceability

Member Function Documentation

init() [1/2]

void QP::QEvt::init ( ) const

inlinenoexcept

Event initialization for dynamic events.

Usage
When QEVT_PAR_INIT is defined, the template QP::QF::q_new() calls the init() member function of the derived event class to initialize the event parameters. The following example illustrates the implicit use of the QP::QEvt::init() initialization for dynamically allocated events.

#ifdef QEVT_PAR_INIT
    // q_new<> calls ReminderEvt::init()
    ReminderEvt const *reminder = QP::QF::q_new<ReminderEvt>(CRUNCH_SIG, 0U);
#else
    ReminderEvt *reminder = QP::QF::q_new<ReminderEvt>(CRUNCH_SIG);
    reminder->iter = 0U;
#endif
    POST(reminder, this);

Forward Traceability

• DVP_QP_PCLP_1511: PCLP-1511 *::init() hides non-virtual member 'QP::QEvt::init()'

Definition at line 120 of file qp.hpp.

init() [2/2]

void QP::QEvt::init ( DynEvt const dummy ) const

inlinenoexcept

Event initialization for dynamic events (overload).

Parameters

[in]

dummy

dummy parameter on which to overload the initialization

Usage
The following example illustrates the implicit use of the QP::QEvt::init(DynEvt) initialization for dynamically allocated events. (When QEVT_PAR_INIT is defined, the template QP::QF::q_new() calls the init() member function of the derived event class to initialize event parameters):

static QP::QEvt const *evtPtr = QP::QF::q_new<QP::QEvt>(MY_SIG, QP::QEvt::DYNAMIC);
. . .

Backward Traceability

• SRS_QP_EVT_40: QP/C++ Framework may be compile-time configurable to allow customized initialization on event instances

Definition at line 123 of file qp.hpp.

Member Data Documentation

sig

std::uint32_t QP::QEvt::sig

Signal of the event (see Event Signal).

Details
The 16-bit sig bitfield stores the event signal, which supports 64K signal space (65,536 unique signals). The lowest 4 signals (values 0..3) are reserved by the QP/C++ Framework. Application-specific signals must not overlap the reserved signals and must start with an offset (see ::Q_USER_SIG).

Example
The following code snippet illustrates a typical definition of Application-specific event signals as an enumeration. Please note the use of the QP::Q_USER_SIG offset.

enum AppSignals : QP::QSignal {
    EAT_SIG = QP::Q_USER_SIG, // published by Table to let a Philo eat
    DONE_SIG,       // published by Philo when done eating
    PAUSE_SIG,      // published by BSP to pause the application
    SERVE_SIG,      // published by BSP to serve restart serving forks
    TEST_SIG,       // published by BSP to test the application
    MAX_PUB_SIG,    // the last published signal
 
    TIMEOUT_SIG,    // posted by time event to Philo
    HUNGRY_SIG,     // posted by hungry Philo to Table
    MAX_SIG         // the last signal
};

Backward Traceability

• SRS_QP_EVT_20: Each event instance shall contain the event Signal.
• SRS_QP_EVT_23: QP/C++ Framework shall provide the lowest numerical value of signals allowed in the Application

Forward Traceability

• DVR_QP_MP2_R12_2_1: Rule 12.2.1(Required): Bit-fields should not be declared

Definition at line 103 of file qp.hpp.

poolNum_

std::uint32_t QP::QEvt::poolNum_

Event pool number of this event.

Details
The 8-bit poolNum_ bitfield stores the event-pool number. For mutable events, the event-pool number is in the range 1..QF_MAX_EPOOL. For immutable (static) events and for time events (instances QP::QTimeEvt), the event-pool number is 0.

Note

QEvt::poolNum_ is for internal use only inside QP/C++ Framework. QP Applications should NOT access this member.

Forward Traceability

• DVR_QP_MP2_R12_2_1: Rule 12.2.1(Required): Bit-fields should not be declared

Definition at line 104 of file qp.hpp.

refCtr_

std::uint32_t QP::QEvt::refCtr_

Event reference counter.

Details
For mutable events (events from event pools), the 8-bit bitfield QEvt::refCtr_ holds the reference count, which must be in the range 0 through (2*QF_MAX_ACTIVE). For immutable (static) events and for time events (instances QP::QTimeEvt), the member QEvt::refCtr_ is not used for reference counting and instead is used as an indicator of the event origin, which is initialized in the macro QEVT_INITIALIZER().

Note

::QEvt::refCtr_ is a private member for internal use only inside QP/C++ Framework. QP Applications should NOT access this member.

Forward Traceability

• DVR_QP_MP2_R12_2_1: Rule 12.2.1(Required): Bit-fields should not be declared

Definition at line 105 of file qp.hpp.

filler_

std::uint32_t QP::QEvt::filler_

Member of QP::QEvt to make it identical size in QP/C++ and SafeQP/C++.

Details
The 32-bit filler_ member ensures that the size of QP::QEvt instances is identical between QP/C++ and SafeQP/C++. This avoids any subtle incompatibilities (related to the size of the event instances, including derived events) in allocating dynamic events from event pools.

Note

QEvt::filler_ is for internal use only inside QP/C++ Framework. QP Applications should NOT access this member.

Forward Traceability

Definition at line 106 of file qp.hpp.

---

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

• qp.hpp
• qp.dox