QP/C  5.8.2
qf_time.c File Reference

QF time events and time management services. More...

#include "qf_port.h"
#include "qf_pkg.h"
#include "qassert.h"
#include "qs_port.h"

Go to the source code of this file.

Macros

#define QP_IMPL   /* this is QP implementation */
 

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

Detailed Description

QF time events and time management services.

Definition in file qf_time.c.

Function Documentation

◆ 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.
Precondition
the tick rate must be in range

Definition at line 196 of file qf_time.c.

◆ 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.
Note
this function should be called only via the macro QF_TICK_X()
the calls to QF_tickX_() with different tickRate argument 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 75 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 291 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]tickRatesystem tick rate to associate with this time event.
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 231 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 495 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 361 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 420 of file qf_time.c.