commented, corrected and beautified both timer and timer group code

git-svn-id: https://ssl.bulix.org/svn/lcd4linux/trunk@1136 3ae390bd-cb1e-0410-b409-cd5a39f66f1f

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;
     }
 }