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
void	init () noexcept
void	init (DynEvt const dummy) noexcept

Public Attributes
QSignal	sig
	Signal of the event (see Event Signal)
std::uint8_t	poolNum_
	Event pool number of this event.
std::uint8_t volatile	refCtr_
	Event reference counter.

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).

Attention

Event parameters must be included in the event instance directly (as opposed to being referenced by pointers or references). Therefore, the QP::QEvt sublcasses are restricted to have both "standard layout" and be "trivially copyable". In QP/C++ this means that QP::QEvt sublcasses 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.

Backward Traceability

• SDS_QP_QEvt: QEvt event class.

Forward Traceability

• QP::QEvt::sig: Signal of the event (see Event Signal)
• QP::QEvt::refCtr_: Event reference counter.
• QP::QEvt::poolNum_: Event pool number of this event

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...
    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 QEvt const myEvt { MY_SIG };
// post, publish, or dispatch the immutable event...
 
// immutable event with parameters
static KeypressEvt const keyEvt {
    KEYPRESS_SIG, // signal
    12U           // .keyId attribute
}
// post, publish, or dispatch the immutable event...
 
// mutable event without parameters (e.g., automatic object inside a function)
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
    sig,  // signal
    keyId // .keyId attribute
};
// dispatch the event (asynchronous posting or publishing probably WRONG!)

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()/QPQF::q_new_x() for code examples of allocating dynamic mutable events.

Definition at line 115 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))

Definition at line 122 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)

Backward Traceability

• SRS_QP_EVT_40: QP Framework may be compile-time configurable to allow customized constructor and other custom operations on event instances

Usage

The following examples illustrate recommended ways to use this 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!)

Backward Traceability

• SDS_QP_QEvt: QEvt event class.

Definition at line 125 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.

Member Function Documentation

init() [1/2]

void QP::QEvt::init ( )

inlinenoexcept

Event initialization for dynamic events

Returns

void

Usage

The following example illustrates the implicit use of the QEvt::QEvt(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);
. . .

Definition at line 132 of file qp.hpp.

init() [2/2]

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

inlinenoexcept

Event initialization for dynamic events

Parameters

[in]

dummy

dummy parameter on which to overload the initialization

Returns

void

Usage

The following example illustrates the implicit use of the QEvt::QEvt(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);
. . .

Definition at line 135 of file qp.hpp.

Member Data Documentation

sig

QSignal QP::QEvt::sig

Signal of the event (see Event Signal)

Backward Traceability

• QP::QEvt: Event class
• SRS_QP_EVT_20: Each event instance shall contain the event Signal

Definition at line 117 of file qp.hpp.

poolNum_

std::uint8_t QP::QEvt::poolNum_

Event pool number of this event.

Details

The 8-bit poolNum_ member 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.

Backward Traceability

• QP::QEvt: Event class
• SRS_QP_EVT_31: Event abstraction may contain other data items for internal event management inside QP Framework
• SRS_QP_EVT_30: QP Framework shall allow Application to create event instances with Parameters defined by the Application

Definition at line 118 of file qp.hpp.

refCtr_

std::uint8_t volatile QP::QEvt::refCtr_

Event reference counter.

Details

For mutable events (events from event pools), the 8-bit member QEvt::refCtr_ holds the reference count, which must be in the rage 0..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.

Backward Traceability

• QP::QEvt: Event class
• SRS_QP_EVT_31: Event abstraction may contain other data items for internal event management inside QP Framework
• SRS_QP_EVT_30: QP Framework shall allow Application to create event instances with Parameters defined by the Application

Definition at line 119 of file qp.hpp.

---

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

• qp.hpp
• qp.dox