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 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.
- See also
- QTimeEvt for the description of the data members
- Traceability
-
- Note
- 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.
-
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 1066 of file qf.h.
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] | me | current instance pointer (see oop) |
[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.
- 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:
static QState Game_show_logo(Tunnel *
const me,
QEvt const *
const e) {
BSP_TICKS_PER_SEC/2U,
BSP_TICKS_PER_SEC/2U);
BSP_TICKS_PER_SEC*5U,
0U);
. . .
break;
}
. . .
void QTimeEvt_armX(QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
Definition at line 113 of file qf_time.c.