QEvt Class Reference

Event class. More...

#include "qp.h"

Inheritance diagram for QEvt:

Static Public Member Functions
static void	QEvt_ctor (QEvt *const me, enum_t const sig)
static QEvt *	QEvt_init (QEvt *const me, uint8_t const dummy)
	Event without parameters initialization.

Public Attributes
QSignal	sig
	Signal of the event (see Event Signal)

Static Private Member Functions
static void	QEvt_refCtr_inc_ (QEvt const *const me)
static void	QEvt_refCtr_dec_ (QEvt const *const me)

Private Attributes
uint8_t	poolNum_
	Event pool number of this event.
uint8_t volatile	refCtr_
	Event reference counter.

Detailed Description

Event class.

Details

Class 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 QEvt sublcasses are restricted to have both "standard layout" and be "trivially copyable". In QP/C this means that 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;

Backward Traceability

• SDS_QP_QEvt: QEvt event class.

Forward Traceability

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

Usage

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

typedef struct {
    QEvt super; // <=== inherit QEvt
    // event parameters follow...
    uint8_t keyId; // ID of the key pressed
} KeypressEvt;

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

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

Note

Please see macros Q_NEW() or Q_NEW_X() for code examples of allocating dynamic mutable events.

Definition at line 114 of file qp.h.

Member Function Documentation

QEvt_ctor()

static void QEvt_ctor ( QEvt *const me, enum_t const sig )

inlinestatic

Definition at line 122 of file qp.h.

QEvt_init()

static QEvt * QEvt_init ( QEvt *const me, uint8_t const dummy )

inlinestatic

Event without parameters initialization.

Details

The main purpose of the QEvt initialization is to support dynamic allocation of events without parameters with the macros Q_NEW() or Q_NEW_X().

Remarks

The QEvt_init() can be also used to initialize event instances (or the portion inherited from QEvt in events with parameters), but this is not recommended. Instead, the recommended ways of instantiating event objects use the RAII principle (Resource Acquisition Is Initialization) and are based on the QEVT_INITIALIZER() macro, as illustrated in the QEvt class.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OO)
[in]	dummy	shall be set to QEVT_DYNAMIC for dynamic events

Returns

Pointer to the initialized event (the me pointer, see SAS_QP_OO).

Backward Traceability

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

Usage

The following example illustrates the use of the QEvt_init() directly (not recommended because not based on RAII):

// mutable event without parameters (type QEvt)
QEvt myEvt; // <== event instance (e.g., on the stack)
QEvt_init(&myEvt, MY_SIG); // <== initialize the event (not recommended)
// dispatch the event (asynchronous posting or publishing probably WRONG!)
 
// mutable event with parameters (type KeypressEvt derived from QEvt)
KeypressEvt keypressEvt; // <== event instance (e.g., on the stack)
QEvt_init(&keypressEvt.super, KEYPRESS_SIG); // <== initialize the .super member
keypressEvt.keyId = 23U; // initialize the event parameter
// dispatch keypressEvt...

The following example illustrates the use of the QEvt_init() implicitly (called by the macro Q_NEW()) when the configuration macro QEVT_PAR_INIT is defined:

// variadic version of Q_NEW() (QEVT_DYNAMIC passed to QEvt_init())
QEvt const *pe = Q_NEW(QEvt, MY_SIG, QEVT_DYNAMIC);
// post or publish the event...

Definition at line 131 of file qp.h.

QEvt_refCtr_inc_()

static void QEvt_refCtr_inc_ ( QEvt const *const me )

inlinestaticprivate

Internal function to increment the refCtr of a const event.

Details

This function requires "casting `const` away" from the event pointer, which violates MISRA-C:2023 Rule 11.8. This function encapsulates this violation.

Backward Traceability

• DVR_QP_MC4_R11_08

Definition at line 60 of file qp_pkg.h.

QEvt_refCtr_dec_()

static void QEvt_refCtr_dec_ ( QEvt const *const me )

inlinestaticprivate

Internal function to decrement the refCtr of a const event.

Details

This function requires "casting `const` away" from the event pointer, which violates MISRA-C:2023 Rule 11.8. This function encapsulates this violation.

Backward Traceability

• DVR_QP_MC4_R11_08

Definition at line 67 of file qp_pkg.h.

Member Data Documentation

sig

QSignal sig

Signal of the event (see Event Signal)

Backward Traceability

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

Definition at line 115 of file qp.h.

poolNum_

uint8_t poolNum_

private

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 QTimeEvt), the event-pool number is 0.

Backward Traceability

• 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 116 of file qp.h.

refCtr_

uint8_t volatile refCtr_

private

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

Backward Traceability

• 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 117 of file qp.h.

---

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

• qp.h
• qp_pkg.h
• qp.dox
• qp_pkg.dox