Time Event class. More...

#include <qp.h>

Inheritance diagram for QTimeEvt:

Public Member Functions
void	QTimeEvt_ctorX (QTimeEvt const me, QActive const act, enum_t const sig, uint_fast8_t const tickRate)
	The "extended" constructor to initialize a Time Event.
void	QTimeEvt_armX (QTimeEvt *const me, uint32_t const nTicks, uint32_t const interval)
	Arm a time event (extended version for one-shot or periodic time event).
bool	QTimeEvt_disarm (QTimeEvt *const me)
	Disarm a time event.
bool	QTimeEvt_rearm (QTimeEvt *const me, uint32_t const nTicks)
	Rearm a time event.
bool	QTimeEvt_wasDisarmed (QTimeEvt *const me)
	Check the "was disarmed" status of a time event.
QTimeEvtCtr	QTimeEvt_getCtr (QTimeEvt const *const me)
	Get the current value of the down-counter of a time event.
Public Member Functions inherited from QEvtPtr
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.

Static Public Member Functions
bool	QTimeEvt_noActive (uint_fast8_t const tickRate)
	Check if any time events are active at a given clock tick rate.

Protected Attributes
QEvt	super

Private Member Functions
QTimeEvt *	QTimeEvt_expire_ (QTimeEvt const me, QTimeEvt const prev_link, QActive const *const act, uint_fast8_t const tickRate)

Static Private Member Functions
void	QTimeEvt_init (void)
void	QTimeEvt_tick_ (uint_fast8_t const tickRate, void const *const sender)
	Processes all armed time events at every clock tick.
void	QTimeEvt_tick1_ (uint_fast8_t const tickRate, void const *const sender)
	Processes one clock tick for QUTest.

Private Attributes
struct QTimeEvt *	next
	Link to the next time event in the list.
void *	act
	Active object that receives the time events.
QTimeEvtCtr	ctr
	Down-counter of the time event.
QTimeEvtCtr	interval
	Interval for periodic time event (zero for one-shot time event).
uint8_t	tickRate
uint8_t	flags
QTimeEvt	QTimeEvt_timeEvtHead_ [QF_MAX_TICK_RATE]
	Static array of heads of linked lists of time events (one for every clock tick rate).

Additional Inherited Members
Public Attributes inherited from QEvtPtr
uint32_t	sig: 16
	Event signal (see Event Signal).

Detailed Description

Time Event class.

Details
Time events are special QF events equipped with the notion of time passage. The basic usage model of the time events is as follows. An active object allocates one or more QTimeEvt objects (provides the storage for them). When the active object needs to arrange for a timeout, it arms one of its time events to fire either just once (one-shot) or periodically. Each time event times out independently from the others so that a QF application can make multiple parallel timeout requests (from the same or different active objects). When QF detects that the appropriate moment has arrived, it inserts the time event directly into the recipient's event queue. The recipient then processes the time event just like any other event.

Time events, as any other QF events, derive from the QEvt base class. Typically, you will use a time event as-is. Still, you can also further derive more specialized time events from it by adding some more data members and/or specialized functions that operate on the specialized time events.

Internally, the armed time events are organized into linked lists–one list for every supported ticking rate. These linked lists are scanned in every invocation of the QTIMEEVT_TICK_X() macro. Only armed (timing out) time events are in the list, so only armed time events consume CPU cycles.

Remarks: QF manages the time events in the QTIMEEVT_TICK_X() macro, which must be called periodically, from the clock tick ISR or from other periodic source. QTIMEEVT_TICK_X() caYou might also use the special QTicker active object.

Note: Even though QTimeEvt is a subclass of QEvt, QTimeEvt instances can NOT be allocated dynamically from event pools. In other words, it is illegal to allocate QTimeEvt instances with the Q_NEW() or Q_NEW_X() macros.

Backward Traceability

SDS_QP_QTimeEvt: QTimeEvt time event class.

Forward Traceability

Definition at line 576 of file qp.h.

Member Function Documentation

◆ QTimeEvt_ctorX()

void QTimeEvt_ctorX	(	QTimeEvt *const	me,
		QActive *const	act,
		enum_t const	sig,
		uint_fast8_t const	tickRate )

The "extended" constructor to initialize a Time Event.

Details
When creating a time event, you must commit it to a specific active object act, tick rate tickRate, and event signal sig. You cannot change these attributes later.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	act	pointer to the active object associated with this time event. The time event will post itself to this AO.
[in]	sig	signal to associate with this time event.
[in]	tickRate	system clock tick rate to associate with this time event in the range [0..15].

Note: You should call QTimeEvt_ctorX() exactly once for every Time Event object before arming the Time Event. The ideal place for calling QTimeEvt_ctorX() is the constructor of the associated AO.

Forward Traceability

Definition at line 50 of file qf_time.c.

◆ QTimeEvt_armX()

void QTimeEvt_armX	(	QTimeEvt *const	me,
		uint32_t const	nTicks,
		uint32_t const	interval )

Arm a time event (extended version for one-shot or periodic time event).

Details
Arms a time event to fire in a specified number of clock ticks and with a specified interval. If the interval is zero, the time event is armed for one shot ('one-shot' time event). When the timeout expires, the time event gets directly posted (using the FIFO policy) into the event queue of the host active object. After posting, a one-shot time event gets automatically disarmed while a periodic time event (interval != 0) is automatically re-armed.

A time event can be disarmed at any time by calling QTimeEvt_disarm(). Also, a time event can be re-armed to fire in a different number of clock ticks by calling the QTimeEvt_rearm().

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	nTicks	number of clock ticks (at the associated rate) to rearm the time event with.
[in]	interval	interval (in clock ticks) for periodic time event.

Attention: Arming an already armed time event is not allowed and is considered a programming error. The QP/C framework will assert if it detects an attempt to arm an already armed time event.

Usage
The following example shows how to arm a periodic time event as well as a one-shot time event from a state machine of an active object:

QState Game_show_logo(Tunnel * const me, QEvt const * const e) {
    QState status_;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            // arm periodic time event
            QTimeEvt_armX(&me->blinkTimeEvt,     // <===
                          BSP_TICKS_PER_SEC/2U,  // one-time delay
                          BSP_TICKS_PER_SEC/2U); // interval
            // arm a one-shot time event
            QTimeEvt_armX(&me->screenTimeEvt,
                          BSP_TICKS_PER_SEC*5U,  // one-time delay
                          0U);      // interval (0 == no interval)
            . . .
            status_ = Q_HANDLED();
            break;
        }
        . . .

Forward Traceability

DVR_QP_MC5_R11_5: MISRA-C:2025 Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object

Definition at line 78 of file qf_time.c.

◆ QTimeEvt_disarm()

bool QTimeEvt_disarm ( QTimeEvt *const me )

Disarm a time event.

Details
Disarm the time event so it can be safely reused.

Remarks: Disarming an already disarmed time event is fine.

Parameters

[in,out] me current instance pointer (see SAS_QP_OOA)

Returns: 'true' if the time event was truly disarmed, that is, it was running. The return of 'false' means that the time event was not truly disarmed, because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case, the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.

Forward Traceability

Definition at line 146 of file qf_time.c.

◆ QTimeEvt_rearm()

bool QTimeEvt_rearm	(	QTimeEvt *const	me,
		uint32_t const	nTicks )

Rearm a time event.

Details
Rearms a time event with a new number of clock ticks. This function can be used to adjust the current period of a periodic time event or to prevent a one-shot time event from expiring (e.g., a watchdog time event). Rearming a periodic timer leaves the interval unchanged and is a convenient method to adjust the phasing of a periodic time event.

Parameters

[in,out]	me	current instance pointer (see SAS_QP_OOA)
[in]	nTicks	number of clock ticks (at the associated rate) to rearm the time event with.

Returns: 'true' if the time event was running as it was re-armed. The 'false' return means that the time event was not truly re-armed because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case, the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.

Forward Traceability

DVR_QP_MC5_R11_5: MISRA-C:2025 Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object

Definition at line 190 of file qf_time.c.

◆ QTimeEvt_wasDisarmed()

bool QTimeEvt_wasDisarmed ( QTimeEvt *const me )

Check the "was disarmed" status of a time event.

Details
Useful for checking whether a one-shot time event was disarmed in the QTimeEvt_disarm() operation.

Parameters

[in,out] me current instance pointer (see SAS_QP_OOA)

Returns: 'true' if the time event was truly disarmed in the last QTimeEvt_disarm() operation. The 'false' return means that the time event was not truly disarmed, because it was not running at that time. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case, the 'false' return means that the time event has already been posted or published and should be expected in the active object's event queue.

Note: This function has a side effect of setting the "was disarmed" status, which means that the second and subsequent times this function is called, the function will return 'true'.

Forward Traceability

Definition at line 262 of file qf_time.c.

◆ QTimeEvt_getCtr()

QTimeEvtCtr QTimeEvt_getCtr ( QTimeEvt const *const me )

Get the current value of the down-counter of a time event.

Details
Useful for checking how many clock ticks (at the tick rate associated with the time event) remain until the time event expires.

Parameters

[in,out] me current instance pointer (see SAS_QP_OOA)

Returns: For an armed time event, the function returns the current value of the down-counter of the given time event. If the time event is not armed, the function returns 0.

Forward Traceability

Definition at line 376 of file qf_time.c.

◆ QTimeEvt_init()

void QTimeEvt_init ( void )

staticprivate

Definition at line 384 of file qf_time.c.

◆ QTimeEvt_tick_()

void QTimeEvt_tick_	(	uint_fast8_t const	tickRate,
		void const *const	sender )

staticprivate

Processes all armed time events at every clock tick.

Details
This internal helper function processes all armed QTimeEvt objects associated with the tick rate tickRate.

This function must be called periodically from a time-tick ISR or from a task so that QF can manage the timeout events assigned to the given system clock tick rate.

Parameters

[in]	tickRate	clock tick rate serviced in this call [1..15].
[in]	sender	pointer to a sender object (only for QS tracing)

Note: This function should be called only via the macro QTIMEEVT_TICK_X().; The calls to QTimeEvt_tick_() with different tickRate parameters can preempt each other. For example, higher clock tick rates might be serviced from interrupts while others from tasks (active objects).

Forward Traceability

DVR_QP_MC5_R11_5: MISRA-C:2025 Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object

Definition at line 278 of file qf_time.c.

◆ QTimeEvt_expire_()

QTimeEvt * QTimeEvt_expire_	(	QTimeEvt *const	me,
		QTimeEvt *const	prev_link,
		QActive const *const	act,
		uint_fast8_t const	tickRate )

private

Definition at line 398 of file qf_time.c.

◆ QTimeEvt_tick1_()

void QTimeEvt_tick1_	(	uint_fast8_t const	tickRate,
		void const *const	sender )

staticprivate

Processes one clock tick for QUTest.

Forward Traceability

Definition at line 274 of file qutest.c.

◆ QTimeEvt_noActive()

bool QTimeEvt_noActive ( uint_fast8_t const tickRate )

static

Check if any time events are active at a given clock tick rate.

Parameters

[in] tickRate system clock tick rate to find out about.

Returns: 'true' if no time events are armed at the given tick rate and 'false' otherwise.

Note: This function should be called in a critical section.

Forward Traceability

Definition at line 363 of file qf_time.c.

Member Data Documentation

◆ super

QEvt super

protected

Definition at line 577 of file qp.h.

◆ next

struct QTimeEvt* next

private

Link to the next time event in the list.

Forward Traceability

Definition at line 579 of file qp.h.

◆ act

void* act

private

Active object that receives the time events.

Forward Traceability

Definition at line 580 of file qp.h.

◆ ctr

QTimeEvtCtr ctr

private

Down-counter of the time event.

Details
The down-counter is decremented by 1 in every QTimeEvt_tick_() call. The time event fires (gets posted or published) when the down-counter reaches zero.

Forward Traceability

Definition at line 581 of file qp.h.

◆ interval

QTimeEvtCtr interval

private

Interval for periodic time event (zero for one-shot time event).

Details
The value of the interval is re-loaded to the internal down-counter when the time event expires, so that the time event keeps timing out periodically.

Forward Traceability

Definition at line 582 of file qp.h.

◆ tickRate

uint8_t tickRate

private

Definition at line 583 of file qp.h.

◆ flags

uint8_t flags

private

Definition at line 584 of file qp.h.

◆ QTimeEvt_timeEvtHead_

QTimeEvt QTimeEvt_timeEvtHead_[QF_MAX_TICK_RATE]

private

Static array of heads of linked lists of time events (one for every clock tick rate).

Forward Traceability

Definition at line 48 of file qp_pkg.h.

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


QP/C 8.1.3 Real-Time Event Framework

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ QTimeEvt_ctorX()

◆ QTimeEvt_armX()

◆ QTimeEvt_disarm()

◆ QTimeEvt_rearm()

◆ QTimeEvt_wasDisarmed()

◆ QTimeEvt_getCtr()

◆ QTimeEvt_init()

◆ QTimeEvt_tick_()

◆ QTimeEvt_expire_()

◆ QTimeEvt_tick1_()

◆ QTimeEvt_noActive()

Member Data Documentation

◆ super

◆ next

◆ act

◆ ctr

◆ interval

◆ tickRate

◆ flags

◆ QTimeEvt_timeEvtHead_