QP/C  6.3.7
qf_time.c File Reference

QTimeEvt implementation and QF system clock tick QF_tickX_()) More...

#include "qf_port.h"
#include "qf_pkg.h"
#include "qassert.h"
#include "qs_port.h"
Include dependency graph for qf_time.c:

Go to the source code of this file.

Functions

void QF_tickX_ (uint_fast8_t const tickRate, void const *const sender)
 Processes all armed time events at every clock tick. More...
 
bool QF_noTimeEvtsActiveX (uint_fast8_t const tickRate)
 Returns 'true' if there are no armed time events at a given tick rate. More...
 
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. More...
 
void QTimeEvt_armX (QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
 Arm a time event (one shot or periodic) for direct event posting. More...
 
bool QTimeEvt_disarm (QTimeEvt *const me)
 Disarm a time event. More...
 
bool QTimeEvt_rearm (QTimeEvt *const me, QTimeEvtCtr const nTicks)
 Rearm a time event. More...
 
bool QTimeEvt_wasDisarmed (QTimeEvt *const me)
 Check the "was disarmed" status of a time event. More...
 
QTimeEvtCtr QTimeEvt_ctr (QTimeEvt const *const me)
 Get the current value of the down-counter of a time event. More...
 

Variables

QTimeEvt QF_timeEvtHead_ [QF_MAX_TICK_RATE]
 heads of linked lists of time events, one for every clock tick rate More...
 

Detailed Description

QTimeEvt implementation and QF system clock tick QF_tickX_())

Definition in file qf_time.c.

Function Documentation

◆ QF_tickX_()

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

Processes all armed time events at every clock tick.

Description
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]tickRatesystem clock tick rate serviced in this call [1..15].
Note
this function should be called only via the macro QF_TICK_X()
the calls to QF_tickX_() 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).
See also
QTimeEvt.

Definition at line 78 of file qf_time.c.

◆ QF_noTimeEvtsActiveX()

bool QF_noTimeEvtsActiveX ( uint_fast8_t const  tickRate)

Returns 'true' if there are no armed time events at a given tick rate.

Description
Find out if any time events are armed at the given clock tick rate.
Parameters
[in]tickRatesystem 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 critical section.

Definition at line 204 of file qf_time.c.

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

Description
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 Object Orientation)
[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 237 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.

Description
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). The time event gets directly posted (using the FIFO policy) into the event queue of the host active object.
Parameters
[in,out]mepointer (see Object Orientation)
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
[in]intervalinterval (in clock ticks) for periodic time event.
Note
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 the QTimeEvt_disarm() function. Also, a time event can be re-armed to fire in a different number of clock ticks by calling the QTimeEvt_rearm() function.
Usage
The following example shows how to arm a one-shot time event from a state machine of an active object:
QState Philo_eating(Philo * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
QTimeEvt_armX(&me->timeEvt, EAT_TIME, 0U); /* one shot */
status = Q_HANDLED();
break;
}
case Q_EXIT_SIG: {
TableEvt *pe;
QTimeEvt_disarm(&me->timeEvt);
pe = Q_NEW(TableEvt, DONE_SIG);
pe->philNum = me->num;
QF_PUBLISH((QEvt *)pe, me);
status = Q_HANDLED();
break;
}
case TIMEOUT_SIG: {
status = Q_TRAN(&Philosopher_thinking);
break;
}
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}
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 296 of file qf_time.c.

◆ QTimeEvt_disarm()

bool QTimeEvt_disarm ( QTimeEvt *const  me)

Disarm a time event.

Description
Disarm the time event so it can be safely reused.
Parameters
[in,out]mepointer (see Object Orientation)
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 368 of file qf_time.c.

◆ QTimeEvt_rearm()

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

Rearm a time event.

Description
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 Object Orientation)
[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 428 of file qf_time.c.

◆ QTimeEvt_wasDisarmed()

bool QTimeEvt_wasDisarmed ( QTimeEvt *const  me)

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

Description
Useful for checking whether a one-shot time event was disarmed in the QTimeEvt_disarm() operation.
Parameters
[in,out]mepointer (see Object Orientation)
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 510 of file qf_time.c.

◆ QTimeEvt_ctr()

QTimeEvtCtr QTimeEvt_ctr ( QTimeEvt const *const  me)

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

Description
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 Object Orientation)
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 532 of file qf_time.c.

Variable Documentation

◆ QF_timeEvtHead_

QTimeEvt QF_timeEvtHead_[QF_MAX_TICK_RATE]

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

Definition at line 53 of file qf_time.c.