Event class. More...

#include <qp.h>

Inheritance diagram for QEvt:

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

Public Attributes
uint32_t	sig: 16
	Event signal (see Event Signal).

Private Member Functions
void	QEvt_refCtr_inc_ (QEvt const *const me)
	Internal function to increment the refCtr of a const event.
void	QEvt_refCtr_dec_ (QEvt const *const me)
	Internal function to decrement the refCtr of a const event.
void	QEvt_update_ (QEvt *const me)
bool	QEvt_verify_ (QEvt const *const me)

Private Attributes
uint32_t	poolNum_: 8
	Event pool number of this event.
uint32_t	refCtr_: 8
	Event reference counter.
uint32_t	filler_
	Member of QEvt to make it identical size in QP/C and SafeQP/C.

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 QEvt to add custom event parameters (see also SDS_QP_QEvt).

Usage
The following example illustrates how to use the QEvt instance directly (event without parameters)

// immutable event without parameters
static QEvt const myEvt = QEVT_INITIALIZER(MY_SIG);
// post, publish, or dispatch the immutable event...

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

Attention

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

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

Backward Traceability

SDS_QP_QEvt: QEvt event class.

Forward Traceability

QSignal: The signal of event QEvt

Definition at line 100 of file qp.h.

Member Function Documentation

◆ QEvt_ctor()

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

QEvt constructor

Details
The QEvt constructor initializes the given QEvt instance with the provided signal. The resulting event is NOT dynamic, meaning that it does NOT come from an event pool and the QP/C Framework won't try to recycle the event.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	sig	event signal (typically enumerated) in the numerical range 0..64K

Example

void QTimeEvt_ctorX(QTimeEvt * const me,
    QActive * const act,
    enum_t const sig,
    uint_fast8_t const tickRate)
{
    . . .
    QEvt_ctor(&me->super, sig); // the superclass' ctor
    . . .
    me->super.refCtr_ = 0U; // adjust from QEvt_ctor(sig)
    . . .

Note: QEvt_ctor() is NOT appropriate for initializing immutable, const events in ROM. Use QEVT_INITIALIZER() for such events.

Forward Traceability

Definition at line 47 of file qf_act.c.

◆ QEvt_init()

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

Event without parameters initialization.

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

Remarks: QEvt_init() can also be 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_OOA)
[in]	dummy	shall be set to QEVT_DYNAMIC for dynamic events

Returns: Pointer to the initialized event (the me pointer, see SAS_QP_OOA).

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

Backward Traceability

Forward Traceability

Definition at line 54 of file qf_act.c.

◆ QEvt_refCtr_inc_()

void QEvt_refCtr_inc_ ( QEvt const *const me )

private

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:2025 Rule 11.8. This function encapsulates this violation.

Backward Traceability

SAS_QP_EVT_00: Event management policy

Forward Traceability

DVR_QP_MC5_R2_2A: MISRA-C:2025 Rule 2.2(Required): A project shall not contain dead code (FALSE-positive)
DVR_QP_MC5_R11_3C: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (unrelated types)
DVR_QP_MC5_R11_8: MISRA-C:2025 Rule 11.8(Required): A cast shall not remove any 'const' or 'volatile' qualification from the type pointer to by a pointer

Definition at line 61 of file qf_act.c.

◆ QEvt_refCtr_dec_()

void QEvt_refCtr_dec_ ( QEvt const *const me )

private

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:2025 Rule 11.8. This function encapsulates this violation.

Backward Traceability

SAS_QP_EVT_00: Event management policy

Forward Traceability

DVR_QP_MC5_R2_2A: MISRA-C:2025 Rule 2.2(Required): A project shall not contain dead code (FALSE-positive)
DVR_QP_MC5_R11_3C: MISRA-C:2025 Rule 11.3(Required): A cast shall not be performed between a pointer to object type and a pointer to a different object type (unrelated types)
DVR_QP_MC5_R11_8: MISRA-C:2025 Rule 11.8(Required): A cast shall not remove any 'const' or 'volatile' qualification from the type pointer to by a pointer

Definition at line 73 of file qf_act.c.

◆ QEvt_update_()

void QEvt_update_ ( QEvt *const me )

private

◆ QEvt_verify_()

bool QEvt_verify_ ( QEvt const *const me )

private

Member Data Documentation

◆ sig

uint32_t sig

Event signal (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 Q_USER_SIG offset.

enum AppSignals {
    EAT_SIG = 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
};

Forward Traceability

Definition at line 101 of file qp.h.

◆ poolNum_

uint32_t poolNum_

private

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

Definition at line 102 of file qp.h.

◆ refCtr_

uint32_t refCtr_

private

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

Definition at line 103 of file qp.h.

◆ filler_

uint32_t filler_

private

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

Details
The 32-bit filler_ member ensures that the size of 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 104 of file qp.h.

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

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ QEvt_ctor()

◆ QEvt_init()

◆ QEvt_refCtr_inc_()

◆ QEvt_refCtr_dec_()

◆ QEvt_update_()

◆ QEvt_verify_()

Member Data Documentation

◆ sig

◆ poolNum_

◆ refCtr_

◆ filler_