Time Event class. More...

#include "qp.hpp"

Inheritance diagram for QP::QTimeEvt:

Public Member Functions
	QTimeEvt (QActive *const act, QSignal const sig, std::uint_fast8_t const tickRate=0U) noexcept
	The "extended" constructor to initialize a Time Event.

void	armX (std::uint32_t const nTicks, std::uint32_t const interval=0U) noexcept

bool	disarm () noexcept

bool	rearm (std::uint32_t const nTicks) noexcept

bool	wasDisarmed () noexcept

void const *	getAct () const noexcept

QTimeEvtCtr	getCtr () const noexcept

QTimeEvtCtr	getInterval () const noexcept

std::uint8_t	getTickRate () const noexcept

QActive *	toActive () noexcept

QTimeEvt *	toTimeEvt () noexcept

Public Member Functions inherited from QP::QEvt
constexpr	QEvt (QSignal const s) noexcept

	QEvt ()=delete

void	init () noexcept

void	init (DynEvt const dummy) noexcept

bool	verify_ () const noexcept
	Internal function to verify the internal integrity of the event instance (QP FuSa Subsystem)

std::uint_fast8_t	getPoolNum_ () const noexcept
	Internal function to get the event pool-number of the given event.

Static Public Member Functions
static void	tick (std::uint_fast8_t const tickRate, void const *const sender) noexcept

static void	tick1_ (std::uint_fast8_t const tickRate, void const *const sender)

static void	tickFromISR (std::uint_fast8_t const tickRate, void par, void const sender) noexcept

static bool	noActive (std::uint_fast8_t const tickRate) noexcept

Static Public Attributes
static QTimeEvt	timeEvtHead_ [QF_MAX_TICK_RATE]

static QPtrDis	timeEvtHead_dis_ [QF_MAX_TICK_RATE]

Private Member Functions
	QTimeEvt () noexcept

	QTimeEvt (QTimeEvt const &other)=delete

QTimeEvt &	operator= (QTimeEvt const &other)=delete

Private Attributes
QTimeEvt *volatile	m_next
	Link to the next time event in the list.

std::uintptr_t	m_next_dis

void *	m_act
	Active object that receives the time events.

QTimeEvtCtr volatile	m_ctr
	Down-counter of the time event.

QTimeEvtCtr	m_ctr_dis

QTimeEvtCtr	m_interval
	Interval for periodic time event (zero for one-shot time event)

std::uint8_t	m_tickRate

std::uint8_t	m_flags

Friends
class	QXThread

Additional Inherited Members
Public Types inherited from QP::QEvt
enum	DynEvt : std::uint8_t { DYNAMIC }

Public Attributes inherited from QP::QEvt
QSignal	sig
	Signal of the event (see Event Signal)

std::uint8_t	evtTag_
	Event "tag" contains pool-ID plus the Duplicate Inverted Storage of the QEvt::refCtr_.

std::uint8_t volatile	refCtr_
	Event reference counter.)

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 QP::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 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 QP::QEvt base class. Typically, you will use a time event as-is, but 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.

Backward Traceability

SDS_QP_QTimeEvt : QTimeEvt time event class.

Note: QF manages the time events in the TICK() or TICK_X() macros, which must be called periodically, from the clock tick ISR or from other periodic source. Instead of TICK()/TICK_X() you might also use the special QP::QTicker active object to defer processing of the armed QP::QTimeEvt objects to the thread level.; Even though QP::QTimeEvt is a subclass of QP::QEvt, QP::QTimeEvt instances can NOT be allocated dynamically from event pools. In other words, it is illegal to allocate QP::QTimeEvt instances with the QP::QF::q_new() or QP::QF::q_new_x() function templates.

Definition at line 927 of file qp.hpp.

Constructor & Destructor Documentation

◆ QTimeEvt() [1/3]

QP::QTimeEvt::QTimeEvt	(	QActive *const	act,
		QSignal const	sig,
		std::uint_fast8_t const	tickRate = 0U )

noexcept

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

Precondition qf_time:300

the signal sig must be valid
the tick rate tickRate must be in range

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

Definition at line 68 of file qf_time.cpp.

◆ QTimeEvt() [2/3]

QP::QTimeEvt::QTimeEvt ( )

privatenoexcept

Definition at line 541 of file qf_time.cpp.

◆ QTimeEvt() [3/3]

QP::QTimeEvt::QTimeEvt ( QTimeEvt const & other )

privatedelete

Member Function Documentation

◆ armX()

void QP::QTimeEvt::armX	(	std::uint32_t const	nTicks,
		std::uint32_t const	interval = 0U )

noexcept

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

Precondition qf_time:400

the host AO must be valid,
the time eveht must be disarmed,
the number of clock ticks cannot be zero,
the signal must be valid.

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.

Backward Traceability

DVR_QP_MC4_R11_05

Usage: The following example shows how to arm a periodic time event as well as 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); // interva

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

}

. . .

QP::QEvt
Event class.
Definition qp.hpp:131

QP::QEvt::sig
QSignal sig
Signal of the event (see Event Signal)
Definition qp.hpp:133

QP::QState
std::uint_fast8_t QState
Type returned from state-handler functions.
Definition qp.hpp:165

Q_HANDLED
#define Q_HANDLED()
Definition qp.hpp:447

Definition at line 98 of file qf_time.cpp.

◆ disarm()

bool QP::QTimeEvt::disarm ( )

noexcept

Disarm a time event.

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

Remarks: Disarming an already disarmed time event is fine.

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.

Definition at line 183 of file qf_time.cpp.

◆ rearm()

bool QP::QTimeEvt::rearm ( std::uint32_t const nTicks )

noexcept

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

Precondition qf_time:600

AO must be valid
tick rate must be in range
nTicks must not be zero,
the signal of this time event must be valid

Backward Traceability

Definition at line 237 of file qf_time.cpp.

◆ wasDisarmed()

bool QP::QTimeEvt::wasDisarmed ( )

noexcept

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.

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

Definition at line 326 of file qf_time.cpp.

◆ getAct()

void const * QP::QTimeEvt::getAct ( ) const

inlinenoexcept

Definition at line 965 of file qp.hpp.

◆ getCtr()

QTimeEvtCtr QP::QTimeEvt::getCtr ( ) const

inlinenoexcept

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.

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.

Definition at line 968 of file qp.hpp.

◆ getInterval()

QTimeEvtCtr QP::QTimeEvt::getInterval ( ) const

inlinenoexcept

Definition at line 971 of file qp.hpp.

◆ getTickRate()

std::uint8_t QP::QTimeEvt::getTickRate ( ) const

inlinenoexcept

Definition at line 974 of file qp.hpp.

◆ tick()

void QP::QTimeEvt::tick	(	std::uint_fast8_t const	tickRate,
		void const *const	sender )

staticnoexcept

Processes all armed time events at every clock tick.

Details: This internal helper function processes all armed QP::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 parameter can preempt each other. For example, higher clock tick rates might be serviced from interrupts while others from tasks (active objects).

Backward Traceability

DVR_QP_MC4_R11_05

Definition at line 341 of file qf_time.cpp.

◆ tick1_()

static void QP::QTimeEvt::tick1_	(	std::uint_fast8_t const	tickRate,
		void const *const	sende )

static

Processes one clock tick for QUTest

◆ tickFromISR()

static void QP::QTimeEvt::tickFromISR	(	std::uint_fast8_t const	tickRate,
		void *	par,
		void const *	sender )

staticnoexcept

◆ noActive()

bool QP::QTimeEvt::noActive ( std::uint_fast8_t const tickRate )

staticnoexcept

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.

Precondition qf_time:800

the tick rate must be in range

Note: This function should be called in critical section.

Definition at line 521 of file qf_time.cpp.

◆ toActive()

QActive * QP::QTimeEvt::toActive ( )

inlinenoexcept

Definition at line 994 of file qp.hpp.

◆ toTimeEvt()

QTimeEvt * QP::QTimeEvt::toTimeEvt ( )

inlinenoexcept

Definition at line 997 of file qp.hpp.

◆ operator=()

QTimeEvt & QP::QTimeEvt::operator= ( QTimeEvt const & other )

privatedelete

Friends And Related Symbol Documentation

◆ QXThread

friend class QXThread

friend

Definition at line 952 of file qp.hpp.

Member Data Documentation

◆ m_next

QTimeEvt* volatile QP::QTimeEvt::m_next

private

Link to the next time event in the list.

Definition at line 929 of file qp.hpp.

◆ m_next_dis

std::uintptr_t QP::QTimeEvt::m_next_dis

private

Definition at line 932 of file qp.hpp.

◆ m_act

void* QP::QTimeEvt::m_act

private

Active object that receives the time events.

Definition at line 934 of file qp.hpp.

◆ m_ctr

QTimeEvtCtr volatile QP::QTimeEvt::m_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.

Definition at line 935 of file qp.hpp.

◆ m_ctr_dis

QTimeEvtCtr QP::QTimeEvt::m_ctr_dis

private

Definition at line 938 of file qp.hpp.

◆ m_interval

QTimeEvtCtr QP::QTimeEvt::m_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.

Definition at line 940 of file qp.hpp.

◆ m_tickRate

std::uint8_t QP::QTimeEvt::m_tickRate

private

Definition at line 941 of file qp.hpp.

◆ m_flags

std::uint8_t QP::QTimeEvt::m_flags

private

Definition at line 942 of file qp.hpp.

◆ timeEvtHead_

QTimeEvt QP::QTimeEvt::timeEvtHead_

static

Array of heads of linked lists of time events, one for every clock tick rate

Definition at line 945 of file qp.hpp.

◆ timeEvtHead_dis_

QPtrDis QP::QTimeEvt::timeEvtHead_dis_

static

Definition at line 948 of file qp.hpp.

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QTimeEvt() [1/3]

◆ QTimeEvt() [2/3]

◆ QTimeEvt() [3/3]

Member Function Documentation

◆ armX()

◆ disarm()

◆ rearm()

◆ wasDisarmed()

◆ getAct()

◆ getCtr()

◆ getInterval()

◆ getTickRate()

◆ tick()

◆ tick1_()

◆ tickFromISR()

◆ noActive()

◆ toActive()

◆ toTimeEvt()

◆ operator=()

Friends And Related Symbol Documentation

◆ QXThread

Member Data Documentation

◆ m_next

◆ m_next_dis

◆ m_act

◆ m_ctr

◆ m_ctr_dis

◆ m_interval

◆ m_tickRate

◆ m_flags

◆ timeEvtHead_

◆ timeEvtHead_dis_