*/
/*
- * exported functions:
+ * Exported functions:
*
* int timer_add(void (*callback) (void *data), void *data, const int
* interval, const int one_shot)
* immediately (useful for scheduling things).
*
*
- * int timer_process (struct timespec *delay)
+ * int timer_process(struct timespec *delay)
*
- * process timer queue
+ * Process timer queue.
*
*
* int timer_remove(void (*callback) (void *data), void *data)
#include <dmalloc.h>
#endif
+/* delay in seconds between timer events that is considered as being
+ induced by clock skew */
#define CLOCK_SKEW_DETECT_TIME_IN_S 1
+/* structure for storing all relevant data of a single timer */
typedef struct TIMER {
+ /* function of type callback(void *data) that will be called when
+ the timer is processed; it will also be used to identify a
+ specific timer */
void (*callback) (void *data);
+
+ /* data which will be passed to the callback function; it will
+ also be used to identify a specific timer */
void *data;
+
+ /* struct to hold the time (in seconds and milliseconds since the
+ Epoch) when the timer will be processed for the next time */
struct timeval when;
+
+ /* specifies the timer's triggering interval in milliseconds */
int interval;
+
+ /* specifies whether the timer should trigger indefinitely until
+ it is deleted (value of 0) or only once (all other values) */
int one_shot;
+
+ /* marks timers as being active (so it will get processed) or
+ inactive (which means the timer has been deleted and its
+ allocated memory may be re-used) */
int active;
} TIMER;
static void timer_inc(struct timeval *tv, const int interval)
/* Update a timer's trigger by adding the given interval.
- tv (timeval pointer): struct holding current time
+ tv (timeval pointer): struct holding the last time the timer has
+ been processed
interval (integer): interval in milliseconds to be added to the
- timer's trigger
+ the last time the timer has been processed
- return value: void */
+ return value: void
+ */
{
+ /* split time interval to be added (given in milliseconds) into
+ microseconds and seconds */
struct timeval diff = {
.tv_sec = interval / 1000,
.tv_usec = (interval % 1000) * 1000
};
+ /* add interval to timer and store the result in the timer */
timeradd(tv, &diff, tv);
}
int timer_remove(void (*callback) (void *data), void *data)
/* Remove a new timer with given callback and data.
- callback (void pointer): function of type callback(void *data);
+ callback (void pointer): function of type void func(void *data);
here, it will be used to identify the timer
data (void pointer): data which will be passed to the callback
function; here, it will be used to identify the timer
return value (integer): returns a value of 0 on successful timer
- deletion; otherwise returns a value of -1 */
+ deletion; otherwise returns a value of -1
+*/
{
int i; /* current timer's ID */
for (i = 0; i < nTimers; i++) {
if (Timers[i].callback == callback && Timers[i].data == data && Timers[i].active) {
/* we have found the timer slot, so mark it as being inactive;
- we will not actually delete the timer, so its memory may be
- re-used */
+ we will not actually delete the timer, so its allocated
+ memory may be re-used */
Timers[i].active = 0;
+
+ /* signal successful timer removal */
return 0;
}
}
int timer_add(void (*callback) (void *data), void *data, const int interval, const int one_shot)
/* Create a new timer and add it to the timer queue.
- callback (void pointer): function of type callback(void *data)
+ callback (void pointer): function of type void func(void *data)
which will be called whenever the timer triggers; this pointer
will also be used to identify a specific timer
other values)
return value (integer): returns a value of 0 on successful timer
- creation; otherwise returns a value of -1 */
+ creation; otherwise returns a value of -1
+*/
{
int i; /* current timer's ID */
struct timeval now; /* struct to hold current time */
break;
}
- /* no inactive timers found, so we have to add a new timer slot */
+ /* no inactive timers (or none at all) found, so we have to add a
+ new timer slot */
if (i >= nTimers) {
/* increment number of timers and (re-)allocate memory used for
storing the timer slots */
/* realloc() has failed */
if (Timers == NULL) {
- /* restore old number of timers and signal unsuccessful timer
- creation */
+ /* restore old number of timers */
nTimers--;
+
+ /* signal unsuccessful timer creation */
return -1;
}
}
Timers[i].one_shot = one_shot;
/* set timer to active so that it is processed and not overwritten
- by the memory optimisation above */
+ by the memory optimisation routine above */
Timers[i].active = 1;
/* one-shot timers should NOT fire immediately, so delay them by a
just as timer_add() does, but the timer will NOT be triggered
immediately (useful for scheduling things).
- callback (void pointer): function of type callback(void *data)
+ callback (void pointer): function of type void func(void *data)
which will be called whenever the timer triggers; this pointer
will also be used to identify a specific timer
other values)
return value (integer): returns a value of 0 on successful timer
- creation; otherwise returns a value of -1 */
+ creation; otherwise returns a value of -1
+*/
{
/* create new timer slot and add it to the timer queue; mask it as
one-shot timer for now, so the timer will be delayed by a
its "one_shot" variable to the REAL value; then signal
successful timer creation */
Timers[i].one_shot = one_shot;
+
+ /* signal successful timer creation */
return 0;
}
}
int timer_process(struct timespec *delay)
+/* Process timer queue.
+
+ delay (timespec pointer): struct holding delay till the next
+ upcoming timer event
+
+ return value (integer): returns a value of 0 when timers have been
+ processed successfully; otherwise returns a value of -1
+*/
{
- int i, min;
- struct timeval now;
+ struct timeval now; /* struct to hold current time */
- /* the current moment */
+ /* get current time to check which timers need processing */
gettimeofday(&now, NULL);
- /* sanity check */
+ /* sanity check; at least one timer should need processing */
if (nTimers == 0) {
- error("huh? not one single timer to process? dazed and confused...");
+ /* otherwise, print an error and return a value of -1 to
+ signal an error */
+ error("Huh? Not one single timer to process? Dazed and confused...");
return -1;
}
- /* process expired timers */
+ int i; /* current timer's ID */
+
+ /* process all expired timers */
for (i = 0; i < nTimers; i++) {
+ /* skip inactive (i.e. deleted) timers */
if (Timers[i].active == 0)
continue;
+ /* check whether current timer needs to be processed, i.e. the
+ timer's triggering time is less than or equal to the current
+ time; according to the man page of timercmp(), this avoids
+ using the operators ">=", "<=" and "==" which might be broken
+ on some systems */
if (!timercmp(&Timers[i].when, &now, >)) {
- /* callback */
+ /* if the timer's callback function has been set, call it and
+ pass the corresponding data */
if (Timers[i].callback != NULL) {
Timers[i].callback(Timers[i].data);
}
- /* respawn or delete timer */
+
+ /* check for one-shot timers */
if (Timers[i].one_shot) {
+ /* mark one-shot timer as inactive (which means the timer has
+ been deleted and its allocated memory may be re-used) */
Timers[i].active = 0;
} else {
+ /* otherwise, respawn timer by adding one triggering interval
+ to its triggering time */
timer_inc(&Timers[i].when, Timers[i].interval);
}
}
}
- /* find next timer */
- min = -1;
+ int min = -1; /* ID of the next upcoming timer */
+
+ /* loop through the timer slots and try to find the next upcoming
+ timer */
for (i = 0; i < nTimers; i++) {
+ /* skip inactive (i.e. deleted) timers */
if (Timers[i].active == 0)
continue;
- if ((min < 0) || timercmp(&Timers[i].when, &Timers[min].when, <))
+
+ /* if this is the first timer that we check, mark it as the next
+ upcoming timer; otherwise, we'll have nothing to compare
+ against in this loop */
+ if (min < 0)
+ min = i;
+ /* check whether current timer needs processing prior to the one
+ selected */
+ else if (timercmp(&Timers[i].when, &Timers[min].when, <))
+ /* if so, mark it as the next upcoming timer */
min = i;
}
+ /* sanity check; we should by now have found the next upcoming
+ timer */
if (min < 0) {
- error("huh? not one single timer left? dazed and confused...");
+ /* otherwise, print an error and return a value of -1 to signal an
+ error */
+ error("Huh? Not one single timer left? Dazed and confused...");
return -1;
}
- /* update the current moment to compensate for processing delay */
+ /* processing all the timers might have taken a while, so update
+ the current time to compensate for processing delay */
gettimeofday(&now, NULL);
- /* delay until next timer event */
- struct timeval diff;
+ struct timeval diff; /* struct holding the time difference
+ between current time and the triggering time of the
+ next upcoming timer event */
+
+ /* calculate delay to the next upcoming timer event and store it
+ in "diff" */
timersub(&Timers[min].when, &now, &diff);
- /* for negative delays, directly trigger next update */
+ /* for negative delays, set "diff" to the Epoch so the next update
+ is triggered immediately */
if (diff.tv_sec < 0)
timerclear(&diff);
- delay->tv_sec = diff.tv_sec;
- /* microseconds to nanoseconds!! */
- delay->tv_nsec = diff.tv_usec * 1000;
+ /* check whether the delay in "diff" has been induced by clock
+ skew */
+ if (diff.tv_sec > CLOCK_SKEW_DETECT_TIME_IN_S) {
+ /* set "diff" to the Epoch so the next update is triggered
+ directly */
+ timerclear(&diff);
- /* check if date changed */
- if ((delay->tv_sec) > CLOCK_SKEW_DETECT_TIME_IN_S) {
- delay->tv_sec = 0;
- delay->tv_nsec = 0;
+ /* display an info message to inform the user */
info("Oops, clock skewed, update timestamp");
+
+ /* update time stamp and timer */
+ /* FIXME: shouldn't we update *all* timers? */
gettimeofday(&now, NULL);
Timers[min].when = now;
}
- return 0;
+ /* finally, set passed timespec "delay" to "diff" ... */
+ delay->tv_sec = diff.tv_sec;
+ /* timespec uses nanoseconds instead of microseconds!!! */
+ delay->tv_nsec = diff.tv_usec * 1000;
+ /* signal successful timer processing */
+ return 0;
}
void timer_exit(void)
/* Release all timers and free the associated memory block.
- return value: void */
+ return value: void
+*/
{
/* reset number of allocated timer slots */
nTimers = 0;
projects / lcd4linux.git / commitdiff