QP/C  7.0.0
Real-Time Embedded Framework
QTimeEvt Struct Reference

#include <qf.h>

Inheritance diagram for QTimeEvt:
QEvt

Public Member Functions

void QTimeEvt_ctorX (QTimeEvt *const me, QActive *const act, enum_t const sig, uint_fast8_t tickRate)
 
void QTimeEvt_armX (QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
 
bool QTimeEvt_rearm (QTimeEvt *const me, QTimeEvtCtr const nTicks)
 
bool QTimeEvt_disarm (QTimeEvt *const me)
 
bool QTimeEvt_wasDisarmed (QTimeEvt *const me)
 
QTimeEvtCtr QTimeEvt_currCtr (QTimeEvt const *const me)
 

Protected Attributes

QEvt super
 

Private Attributes

struct QTimeEvt *volatile next
 
void *volatile act
 
QTimeEvtCtr volatile ctr
 
QTimeEvtCtr interval
 

Additional Inherited Members

- Data Fields inherited from QEvt
QSignal sig
 

Detailed Description

Time Event class

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 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 structure. 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 QF_TICK_X() macro. Only armed (timing out) time events are in the list, so only armed time events consume CPU cycles.

See also
QTimeEvt for the description of the data members
oop
Traceability:
traces to: AQP215
Note
QF manages the time events in the QF_TICK_X() macro, which must be called periodically, from the clock tick ISR or from other periodic source. QF_TICK_X() caYou might also use the special QTicker active object.
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.

Definition at line 456 of file qf.h.

Member Function Documentation

◆ QTimeEvt_ctorX()

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

The extended "constructor" to initialize a Time Event.

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]mepointer (see oop)
[in]actpointer to the active object associated with this time event. The time event will post itself to this AO.
[in]sigsignal to associate with this time event.
[in]tickRatesystemclock tick rate to associate with this time event in the range [0..15].
Note
You should call the constructor exactly once for every Time Event object before arming the Time Event. The ideal place for initializing the time event(s) associated with a given AO is the AO's constructor.
Precondition
The signal must be valid and the tick rate in range

Definition at line 239 of file qf_time.c.

◆ QTimeEvt_armX()

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

Arm a time event (one shot or periodic) for direct event posting.

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]mepointer (see oop)
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
[in]intervalinterval (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 one-shot time event from a state machine of an active object:
QState Blinky_off(Blinky * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
BSP_ledOff();
status = Q_HANDLED();
break;
}
case TIMEOUT_SIG: {
status = Q_TRAN(&Blinky_on);
break;
}
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}
#define Q_HANDLED()
Definition: qep.h:554
#define Q_TRAN(target_)
Definition: qep.h:526
uint_fast8_t QState
Definition: qep.h:170
#define Q_SUPER(super_)
Definition: qep.h:548
@ Q_ENTRY_SIG
Definition: qep.h:688
Definition: qep.h:119
QSignal sig
Definition: qep.h:123
Precondition
the host AO must be valid, time evnet must be disarmed, number of clock ticks cannot be zero, and the signal must be valid.

Definition at line 301 of file qf_time.c.

◆ QTimeEvt_rearm()

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

Rearm a time event.

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]mepointer (see oop)
[in]nTicksnumber 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
AO must be valid, tick rate must be in range, nTicks must not be zero, and the signal of this time event must be valid

Definition at line 444 of file qf_time.c.

◆ QTimeEvt_disarm()

bool QTimeEvt_disarm ( QTimeEvt *const  me)

Disarm a time event.

Disarm the time event so it can be safely reused.

Parameters
[in,out]mepointer (see oop)
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.
Note
there is no harm in disarming an already disarmed time event

Definition at line 380 of file qf_time.c.

◆ QTimeEvt_wasDisarmed()

bool QTimeEvt_wasDisarmed ( QTimeEvt *const  me)

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

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

Parameters
[in,out]mepointer (see oop)
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 530 of file qf_time.c.

◆ QTimeEvt_currCtr()

QTimeEvtCtr QTimeEvt_currCtr ( QTimeEvt const *const  me)

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

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]mepointer (see oop)
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.
Note
The function is thread-safe.

Definition at line 553 of file qf_time.c.

Field Documentation

◆ super

QEvt super
protected

inherits QEvt

Definition at line 457 of file qf.h.

◆ next

struct QTimeEvt* volatile next
private

link to the next time event in the list

Definition at line 460 of file qf.h.

◆ act

void* volatile act
private

the active object that receives the time events

Definition at line 463 of file qf.h.

◆ ctr

QTimeEvtCtr volatile ctr
private

internal down-counter of the time event.

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

Definition at line 471 of file qf.h.

◆ interval

QTimeEvtCtr interval
private

interval for periodic time event (zero for one-shot time event)

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 480 of file qf.h.


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