aboutsummaryrefslogtreecommitdiffstats
path: root/timer_group.c
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--timer_group.c550
1 files changed, 423 insertions, 127 deletions
diff --git a/timer_group.c b/timer_group.c
index 0a72e84..893e085 100644
--- a/timer_group.c
+++ b/timer_group.c
@@ -1,10 +1,11 @@
/* $Id$
* $URL$
*
- * generic grouping of widget timers that have been set to the same
- * update interval, thus allowing synchronized updates
+ * Generic grouping of widgets that have been set to the same update
+ * interval, thus allowing synchronized updates.
*
* Copyright (C) 2010 Martin Zuther <code@mzuther.de>
+ * Copyright (C) 2010 The LCD4Linux Team <lcd4linux-devel@users.sourceforge.net>
*
* Based on "timer.c" which is
* Copyright (C) 2003, 2004 Michael Reinelt <michael@reinelt.co.at>
@@ -26,28 +27,32 @@
*
*/
-/*
- * exported functions:
+/*
+ * Exported functions:
*
- * int timer_add_group(void (*callback) (void *data), const int interval)
- * make sure that generic timer exists for given update interval
+ * void timer_process_group(void *data)
*
- * int timer_remove_group(void (*callback) (void *data), const int interval)
- * remove generic timer for given update interval
+ * Process all widgets of a timer group; if the timer group only
+ * contains one-shot timers, it will be deleted after processing.
*
- * void timer_process_group(void *data)
- * process all widgets of a given update interval (*data)
*
* void timer_exit_group(void)
- * release all timers and free reserved memory
*
- * int timer_add_widget(void (*callback) (void *data), void *data, const int interval, const int one_shot)
- * add widget to group of the given update interval (creates a new group if
- * necessary)
+ * Release all timer groups and widgets and free the associated
+ * memory blocks.
+ *
+ *
+ * int timer_add_widget(void (*callback) (void *data), void *data,
+ * const int interval, const int one_shot)
+ *
+ * Add widget to timer group of the specified update interval
+ * (also creates a new timer group if necessary).
+ *
*
* int timer_remove_widget(void (*callback) (void *data), void *data)
- * remove widget from group of the given update interval (als removes emtpy
- * groups)
+ *
+ * Remove widget from the timer group with the specified update
+ * interval (also removes corresponding timer group if empty).
*
*/
@@ -68,194 +73,485 @@
#endif
-/* contains the actual timers, one for each update interval */
+/* structure for storing all relevant data of a single timer group */
typedef struct TIMER_GROUP {
- void (*callback) (void *data);
+ /* pointer to the group's triggering interval in milliseconds;
+ this will be used to identify a specific timer group and also
+ as callback data for the underlying generic timer */
int *interval;
+
+ /* marks timer group as being active (so it will get processed) or
+ inactive (which means the timer group has been deleted and its
+ allocated memory may be re-used) */
int active;
} TIMER_GROUP;
-TIMER_GROUP *GroupTimers = NULL;
-int nGroupTimers = 0;
+/* number of allocated timer group slots */
+int nTimerGroups = 0;
+
+/* pointer to memory allocated for storing the timer group slots */
+TIMER_GROUP *TimerGroups = NULL;
-/* contains callback and data for each widget */
-typedef struct SINGLE_TIMER {
+
+/* structure for storing all relevant timer data of a single widget */
+typedef struct TIMER_GROUP_WIDGET {
+ /* pointer to function of type void func(void *data) that will be
+ called when the timer is processed; it will also be used to
+ identify a specific widget */
void (*callback) (void *data);
+
+ /* pointer to data which will be passed to the callback function;
+ it will also be used to identify a specific widget */
void *data;
+
+ /* specifies the timer's triggering interval in milliseconds; it
+ will also be used to identify a specific widget */
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 timer 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;
-} SINGLE_TIMER;
+} TIMER_GROUP_WIDGET;
+
+/* number of allocated widget slots */
+int nTimerGroupWidgets = 0;
+
+/* pointer to memory allocated for storing the widget slots */
+TIMER_GROUP_WIDGET *TimerGroupWidgets = NULL;
+
+
+int timer_group_exists(const int interval)
+/* Check whether a timer group for the specified interval exists.
-SINGLE_TIMER *SingleTimers = NULL;
-int nSingleTimers = 0;
+ interval (integer): the sought-after triggering interval in
+ milliseconds
-int timer_add_group(void (*callback) (void *data), const int interval)
+ return value (integer): returns a value of 1 if timer group
+ exists; otherwise returns a value of 0
+*/
{
- int group;
+ int group; /* current timer group's ID */
- /* check whether timer exists for given update interval */
- for (group = 0; group < nGroupTimers; group++) {
- if (*GroupTimers[group].interval == interval)
- return 0;
+ /* loop through the timer group slots to search for one that
+ matches the specified interval */
+ for (group = 0; group < nTimerGroups; group++) {
+ /* skip inactive (i.e. deleted) timer groups */
+ if (TimerGroups[group].active == 0)
+ continue;
+
+ if (*TimerGroups[group].interval == interval) {
+ /* matching timer group found, so signal success by returning
+ a value of 1 */
+ return 1;
+ }
}
- /* otherwise look for a free group */
- for (group = 0; group < nGroupTimers; group++) {
- if (GroupTimers[group].active == 0)
+ /* matching timer group not found, so signal failure by returning
+ a value of 0 */
+ return 0;
+}
+
+
+int timer_add_group(const int interval)
+/* Create a new timer group (unless it already exists) and link it to
+ the timer queue.
+
+ interval (integer): the new timer group's triggering interval in
+ milliseconds
+
+ return value (integer): returns a value of 0 on successful timer
+ group creation; otherwise returns a value of -1
+*/
+{
+ /* if timer group for update interval already exists, signal
+ success by returning a value of 0 */
+ if (timer_group_exists(interval))
+ return 0;
+
+ /* display an info message to inform the user that a new timer
+ group is being created */
+ info("Creating new timer group (%d ms)", interval);
+
+ int group; /* current timer group's ID */
+
+ /* try to minimize memory usage by looping through timer group
+ slots and looking for an inactive timer group */
+ for (group = 0; group < nTimerGroups; group++) {
+ if (TimerGroups[group].active == 0) {
+ /* we've just found one, so let's reuse it ("group" holds its
+ ID) by breaking the loop */
break;
+ }
}
- /* none found, allocate a new group */
- if (group >= nGroupTimers) {
- nGroupTimers++;
- GroupTimers = realloc(GroupTimers, nGroupTimers * sizeof(*GroupTimers));
+ /* no inactive timer groups (or none at all) found, so we have to
+ add a new timer group slot */
+ if (group >= nTimerGroups) {
+ /* increment number of timer groups and (re-)allocate memory used
+ for storing the timer group slots */
+ nTimerGroups++;
+ TimerGroups = realloc(TimerGroups, nTimerGroups * sizeof(*TimerGroups));
- /* also allocate memory for callback data */
- GroupTimers[group].interval = malloc(sizeof(int));
+ /* make sure "group" points to valid memory */
+ group = nTimerGroups - 1;
+
+ /* realloc() has failed */
+ if (TimerGroups == NULL) {
+ /* restore old number of timer groups */
+ nTimerGroups--;
+
+ /* signal unsuccessful timer group creation */
+ return -1;
+ }
+
+ /* allocate memory for the underlying generic timer's callback
+ data (i.e. the group's triggering interval in milliseconds) */
+ TimerGroups[group].interval = malloc(sizeof(int));
+
+ /* malloc() has failed */
+ if (TimerGroups[group].interval == NULL) {
+ /* signal unsuccessful timer group creation */
+ return -1;
+ }
}
- /* initialize group */
- info("Creating new timer group (%d ms)", interval);
+ /* initialize timer group's interval */
+ *TimerGroups[group].interval = interval;
- GroupTimers[group].callback = callback;
- *GroupTimers[group].interval = interval;
- GroupTimers[group].active = 1;
+ /* set timer group to active so that it is processed and not
+ overwritten by the memory optimization routine above */
+ TimerGroups[group].active = 1;
- /* finally, request a generic timer */
- return timer_add(GroupTimers[group].callback, GroupTimers[group].interval, interval, 0);
+ /* finally, request a generic timer that calls this group and
+ signal success or failure */
+ return timer_add(timer_process_group, TimerGroups[group].interval, interval, 0);
}
-int timer_remove_group(void (*callback) (void *data), const int interval)
+
+int timer_remove_group(const int interval)
+/* Remove a timer group and unlink it from the timer queue (also
+ removes all remaining widget slots in this timer group).
+
+ interval (integer): triggering interval in milliseconds; here, it
+ will be used to identify the timer group
+
+ return value (integer): returns a value of 0 on successful timer
+ group removal; otherwise returns a value of -1
+*/
{
- int group;
+ /* display an info message to inform the user that a timer group
+ is being removed */
+ info("Removing timer group (%d ms)", interval);
+
+ int group; /* current timer group's ID */
+ int widget; /* current widget's ID */
+
+ /* loop through the widget slots to look for remaining widgets
+ with the specified update interval */
+ for (widget = 0; widget < nTimerGroupWidgets; widget++) {
+ /* skip inactive (i.e. deleted) widget slots */
+ if (TimerGroupWidgets[widget].active == 0)
+ continue;
+
+ if (TimerGroupWidgets[widget].interval == interval) {
+ /* we have found a matching widget slot, so mark it as being
+ inactive; we will not actually delete the slot, so its
+ allocated memory may be re-used */
+ TimerGroupWidgets[widget].active = 0;
+ }
+ }
- /* look for group with given callback function and update interval */
- for (group = 0; group < nGroupTimers; group++) {
- if (GroupTimers[group].callback == callback && *GroupTimers[group].interval == interval
- && GroupTimers[group].active) {
- /* inactivate group */
- GroupTimers[group].active = 0;
+ /* loop through timer group slots and try to find the specified
+ timer group slot by looking for its settings */
+ for (group = 0; group < nTimerGroups; group++) {
+ /* skip inactive (i.e. deleted) timer groups */
+ if (TimerGroups[group].active == 0)
+ continue;
- /* remove generic timer */
- return timer_remove(GroupTimers[group].callback, GroupTimers[group].interval);
+ if (*TimerGroups[group].interval == interval) {
+ /* we have found the timer group slot, so mark it as being
+ inactive; we will not actually delete the slot, so its
+ allocated memory may be re-used */
+ TimerGroups[group].active = 0;
+
+ /* remove the generic timer that calls this group */
+ if (timer_remove(timer_process_group, TimerGroups[group].interval)) {
+ /* signal successful removal of timer group */
+ return 0;
+ } else {
+ /* an error occurred on generic timer removal, so signal
+ failure by returning a value of -1 */
+ return -1;
+ }
}
}
+
+ /* we have NOT found the timer group slot, so signal failure by
+ returning a value of -1 */
return -1;
}
+
+int timer_remove_empty_group(const int interval)
+/* Remove timer group *only* if it contains no more widget slots.
+
+ interval (integer): triggering interval in milliseconds; here, it
+ will be used to identify the timer group
+
+ return value (integer): returns a value of 0 on successful
+ processing; otherwise returns a value of -1
+*/
+{
+ int widget; /* current widget's ID */
+
+ /* loop through the widget slots to look for widgets with the
+ specified update interval */
+ for (widget = 0; widget < nTimerGroupWidgets; widget++) {
+ /* skip inactive (i.e. deleted) widget slots */
+ if (TimerGroupWidgets[widget].active == 0)
+ continue;
+
+ /* at least one other widget with specified update interval
+ exists, so signal success by returning a value of 0 */
+ if (TimerGroupWidgets[widget].interval == interval)
+ return 0;
+ }
+
+ /* no other widgets with specified update interval exist, so
+ remove corresponding timer group and signal success or
+ failure */
+ return timer_remove_group(interval);
+}
+
+
void timer_process_group(void *data)
+/* Process all widgets of a timer group; if the timer group only
+ contains one-shot timers, it will be deleted after processing.
+
+ data (void pointer): points to an integer holding the triggering
+ interval in milliseconds; here, it will be used to identify the
+ timer group
+
+ return value: void
+*/
{
- int slot;
- int *interval = (int *) data;
+ int widget; /* current widget's ID */
+
+ /* convert callback data to integer (triggering interval in
+ milliseconds) */
+ int interval = *((int *) data);
+
+ /* sanity check; by now, at least one timer group should be
+ instantiated */
+ if (nTimerGroups <= 0) {
+ /* otherwise, print an error and return early */
+ error("Huh? Not even a single timer group to process? Dazed and confused...");
+ return;
+ }
- /* sanity check */
- if (nSingleTimers == 0) {
- error("huh? not even a single widget timer to process? dazed and confused...");
+ /* sanity check; by now, at least one widget slot should be
+ instantiated */
+ if (nTimerGroupWidgets <= 0) {
+ /* otherwise, print an error and return early */
+ error("Huh? Not even a single widget slot to process? Dazed and confused...");
return;
}
- /* process every (active) widget associated with given update interval */
- for (slot = 0; slot < nSingleTimers; slot++) {
- if (SingleTimers[slot].active == 0)
+ /* loop through widgets and search for those matching the timer
+ group's update interval */
+ for (widget = 0; widget < nTimerGroupWidgets; widget++) {
+ /* skip inactive (i.e. deleted) widgets */
+ if (TimerGroupWidgets[widget].active == 0)
continue;
- if (SingleTimers[slot].interval == *interval) {
- /* call one-shot timers only once */
- if (SingleTimers[slot].one_shot)
- SingleTimers[slot].active = 0;
- /* execute callback function */
- if (SingleTimers[slot].callback != NULL)
- SingleTimers[slot].callback(SingleTimers[slot].data);
+ /* the current widget belongs to the specified timer group */
+ if (TimerGroupWidgets[widget].interval == interval) {
+ /* if the widget's callback function has been set, call it and
+ pass the corresponding data */
+ if (TimerGroupWidgets[widget].callback != NULL)
+ TimerGroupWidgets[widget].callback(TimerGroupWidgets[widget].data);
+
+ /* mark one-shot widget as inactive (which means the it has
+ been deleted and its allocated memory may be re-used) */
+ if (TimerGroupWidgets[widget].one_shot) {
+ TimerGroupWidgets[widget].active = 0;
+
+ /* also remove the corresponding timer group if it is empty */
+ timer_remove_empty_group(interval);
+ }
}
}
}
+
int timer_add_widget(void (*callback) (void *data), void *data, const int interval, const int one_shot)
-{
- int slot;
+/* Add widget to timer group of the specified update interval
+ (also creates a new timer group if necessary).
- /* make sure that group for update interval exists or can be created */
- if (timer_add_group(timer_process_group, interval) != 0)
- return -1;
+ callback (void pointer): function of type void func(void *data)
+ which will be called whenever the timer group triggers; this
+ pointer will also be used to identify a specific widget
+
+ data (void pointer): data which will be passed to the callback
+ function; this pointer will also be used to identify a specific
+ widget
+
+ interval (integer): specifies the timer's triggering interval in
+ milliseconds
- /* find a free slot for callback data */
- for (slot = 0; slot < nSingleTimers; slot++) {
- if (SingleTimers[slot].active == 0)
+ one_shot (integer): specifies whether the timer should trigger
+ indefinitely until it is deleted (value of 0) or only once (all
+ other values)
+
+ return value (integer): returns a value of 0 on successful widget
+ addition; otherwise returns a value of -1
+*/
+{
+ int widget; /* current widget's ID */
+
+ /* if no timer group for update interval exists, create one */
+ if (!timer_group_exists(interval)) {
+ /* creation of new timer group failed, so signal failure by
+ returning a value of -1 */
+ if (timer_add_group(interval) != 0)
+ return -1;
+ }
+
+ /* try to minimize memory usage by looping through the widget
+ slots and looking for an inactive widget slot */
+ for (widget = 0; widget < nTimerGroupWidgets; widget++) {
+ if (TimerGroupWidgets[widget].active == 0) {
+ /* we've just found one, so let's reuse it ("widget" holds its
+ ID) by breaking the loop */
break;
+ }
}
- /* none found, allocate a new slot */
- if (slot >= nSingleTimers) {
- nSingleTimers++;
- SingleTimers = realloc(SingleTimers, nSingleTimers * sizeof(*SingleTimers));
+ /* no inactive widget slots (or none at all) found, so we have to
+ add a new widget slot */
+ if (widget >= nTimerGroupWidgets) {
+ /* increment number of widget slots and (re-)allocate memory used
+ for storing the widget slots */
+ nTimerGroupWidgets++;
+ TimerGroupWidgets = realloc(TimerGroupWidgets, nTimerGroupWidgets * sizeof(*TimerGroupWidgets));
+
+ /* make sure "widget" points to valid memory */
+ widget = nTimerGroupWidgets - 1;
+
+ /* realloc() has failed */
+ if (TimerGroupWidgets == NULL) {
+ /* restore old number of widget slots */
+ nTimerGroupWidgets--;
+
+ /* signal unsuccessful creation of widget slot */
+ return -1;
+ }
}
- /* fill slot with callback data */
- SingleTimers[slot].callback = callback;
- SingleTimers[slot].data = data;
- SingleTimers[slot].interval = interval;
- SingleTimers[slot].one_shot = one_shot;
- SingleTimers[slot].active = 1;
+ /* initialize widget slot */
+ TimerGroupWidgets[widget].callback = callback;
+ TimerGroupWidgets[widget].data = data;
+ TimerGroupWidgets[widget].interval = interval;
+ TimerGroupWidgets[widget].one_shot = one_shot;
+ /* set widget slot to active so that it is processed and not
+ overwritten by the memory optimization routine above */
+ TimerGroupWidgets[widget].active = 1;
+
+ /* signal successful addition of widget slot */
return 0;
}
+
int timer_remove_widget(void (*callback) (void *data), void *data)
+/* Remove widget from the timer group with the specified update
+ interval (also removes corresponding timer group if empty).
+
+ callback (void pointer): function of type void func(void *data);
+ here, it will be used to identify a specific widget
+
+ data (void pointer): data which will be passed to the callback
+ function; here, it will be used to identify a specific widget
+
+ return value (integer): returns a value of 0 on successful widget
+ removal; otherwise returns a value of -1
+*/
{
- int slot, interval;
-
- interval = 0;
- /* look for (active) widget with given callback function and data */
- for (slot = 0; slot < nSingleTimers; slot++) {
- if (SingleTimers[slot].callback == callback && SingleTimers[slot].data == data && SingleTimers[slot].active) {
- /* deactivate widget */
- SingleTimers[slot].active = 0;
- interval = SingleTimers[slot].interval;
+ int widget; /* current widget's ID */
+ int interval = -1; /* specified widget's triggering interval in
+ milliseconds */
+
+ /* loop through the widget slots and try to find the specified
+ widget slot by looking for its settings */
+ for (widget = 0; widget < nTimerGroupWidgets; widget++) {
+ /* skip inactive (i.e. deleted) widget slots */
+ if (TimerGroupWidgets[widget].active == 0)
+ continue;
+
+ if (TimerGroupWidgets[widget].callback == callback && TimerGroupWidgets[widget].data == data) {
+ /* we have found the widget slot, so mark it as being
+ inactive; we will not actually delete the slot, so its
+ allocated memory may be re-used */
+ TimerGroupWidgets[widget].active = 0;
+
+ /* store the widget's triggering interval for later use and
+ break the loop */
+ interval = TimerGroupWidgets[widget].interval;
break;
}
}
- /* signal an error if no matching widget was found */
- if (interval == 0)
+ /* if no matching widget was found, signal an error by returning
+ a value of -1 */
+ if (interval < 0)
return -1;
- /* look for other widgets with given update interval */
- for (slot = 0; slot < nSingleTimers; slot++) {
- if (SingleTimers[slot].active == 0)
- continue;
- /* at least one other widget with given update interval exists */
- if (SingleTimers[slot].interval == interval)
- return 0;
- }
-
- /* remove group with given update interval */
- return timer_remove_group(timer_process_group, interval);
+ /* if no other widgets with specified update interval exist,
+ remove corresponding timer group and signal success or
+ failure */
+ return timer_remove_empty_group(interval);
}
+
void timer_exit_group(void)
+/* Release all timer groups and widgets and free the associated
+ memory blocks.
+
+ return value: void
+*/
{
- int group;
+ int group; /* current timer group's ID */
+
+ /* loop through all timer groups and remove them one by one */
+ for (group = 0; group < nTimerGroups; group++) {
+ /* remove generic timer */
+ timer_remove(timer_process_group, TimerGroups[group].interval);
- /* remove generic timer and free memory for callback data */
- for (group = 0; group < nGroupTimers; group++) {
- timer_remove(GroupTimers[group].callback, GroupTimers[group].interval);
- free(GroupTimers[group].interval);
+ /* free memory allocated for callback data (i.e. the group's
+ triggering interval in milliseconds) */
+ free(TimerGroups[group].interval);
}
- /* free memory for groups */
- nGroupTimers = 0;
+ /* reset number of allocated timer groups */
+ nTimerGroups = 0;
- if (GroupTimers != NULL) {
- free(GroupTimers);;
- GroupTimers = NULL;
+ /* free allocated memory containing the timer group slots */
+ if (TimerGroups != NULL) {
+ free(TimerGroups);
+ TimerGroups = NULL;
}
- /* free memory for widget callback data */
- nSingleTimers = 0;
+ /* reset number of allocated widget slots */
+ nTimerGroupWidgets = 0;
- if (SingleTimers != NULL) {
- free(SingleTimers);;
- SingleTimers = NULL;
+ /* free allocated memory containing the widget slots */
+ if (TimerGroupWidgets != NULL) {
+ free(TimerGroupWidgets);
+ TimerGroupWidgets = NULL;
}
}