timer: clean up.

Add examples and a documentation fix.
Remove unused cascade function (was used in initial always-step-1-bucket
 version).
Restore timers_dump() to within CCAN_TIMER_DEBUG.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

diff --git a/ccan/timer/timer.c b/ccan/timer/timer.c
index 59d1ff377cb6498e01ffbed8cad1ef4290466fdf..991ec643926f330a897ba383265343f1ae280e65 100644 (file)
--- a/ccan/timer/timer.c
+++ b/ccan/timer/timer.c
@@ -119,41 +119,6 @@ static void add_level(struct timers *timers, unsigned int level)
                timer_add_raw(timers, t);
 }
 
-/* Take timers from level and distribute them down one. */
-static void cascade(struct timers *timers, unsigned int level)
-{
-       struct timer *i;
-       struct list_head from_far, *list;
-
-       if (level == ARRAY_SIZE(timers->level) || !timers->level[level]) {
-               list_head_init(&from_far);
-               timers_far_get(timers, &from_far,
-                              timers->base
-                              + (1ULL << (level*TIMER_LEVEL_BITS))-1);
-               list = &from_far;
-               if (level != ARRAY_SIZE(timers->level))
-                       add_level(timers, level);
-       } else {
-               unsigned src;
-
-               src = (timers->base >> (level * TIMER_LEVEL_BITS)) % PER_LEVEL;
-               if (src == 0)
-                       cascade(timers, level + 1);
-               list = &timers->level[level]->list[src];
-       }
-
-       while ((i = list_pop(list, struct timer, list)) != NULL) {
-               unsigned dst;
-
-               assert(i->time >= timers->base);
-               assert(i->time < (timers->base
-                                 + (1ULL << ((level+1)*TIMER_LEVEL_BITS))));
-
-               dst = (i->time >> ((level-1)*TIMER_LEVEL_BITS)) % PER_LEVEL;
-               list_add_tail(&timers->level[level-1]->list[dst], &i->list);
-       }
-}
-
 static const struct timer *find_first(const struct list_head *list,
                                      const struct timer *prev)
 {
@@ -409,7 +374,7 @@ past_levels:
        return (struct timers *)timers;
 }
 
-//#ifdef CCAN_TIMER_DEBUG
+#ifdef CCAN_TIMER_DEBUG
 void timers_dump(const struct timers *timers, FILE *fp)
 {
        unsigned int l, i;
@@ -455,7 +420,7 @@ void timers_dump(const struct timers *timers, FILE *fp)
        }
        fprintf(stderr, "Far: %llu (%llu-%llu)\n", num, min, max);
 }
-//#endif
+#endif
 
 void timers_cleanup(struct timers *timers)
 {

diff --git a/ccan/timer/timer.h b/ccan/timer/timer.h
index 65f849b3dccc22743ed958a6d36ddb04370c2b65..d6e81e8cacbf2dfe94f3d73468e8a70aa12caa7c 100644 (file)
--- a/ccan/timer/timer.h
+++ b/ccan/timer/timer.h
@@ -25,6 +25,11 @@ struct timer;
  *
  * This sets up a timers struct: any timers added before @start will be
  * set to expire immediately.
+ *
+ * Example:
+ *     struct timers timeouts;
+ *
+ *     timers_init(&timeouts, time_now());
  */
 void timers_init(struct timers *timers, struct timespec start);
 
@@ -33,6 +38,9 @@ void timers_init(struct timers *timers, struct timespec start);
  * @timers: the struct timers
  *
  * This frees any timer layers allocated during use.
+ *
+ * Example:
+ *     timers_cleanup(&timeouts);
  */
 void timers_cleanup(struct timers *timers);
 
@@ -44,6 +52,12 @@ void timers_cleanup(struct timers *timers);
  *
  * This efficiently adds @timer to @timers, to expire @when (rounded to
  * TIMER_GRANULARITY nanoseconds).
+ *
+ * Example:
+ *     struct timer t;
+ *
+ *     // Timeout in 100ms.
+ *     timer_add(&timeouts, &t, time_add(time_now(), time_from_msec(100)));
  */
 void timer_add(struct timers *timers, struct timer *timer,
               struct timespec when);
@@ -54,6 +68,9 @@ void timer_add(struct timers *timers, struct timer *timer,
  * @timer: the timer previously added with timer_add()
  *
  * This efficiently removes @timer from @timers.
+ *
+ * Example:
+ *     timer_del(&timeouts, &t);
  */
 void timer_del(struct timers *timers, struct timer *timer);
 
@@ -65,11 +82,15 @@ void timer_del(struct timers *timers, struct timer *timer);
  * This returns false, and doesn't alter @first if there are no
  * timers.  Otherwise, it sets @first to the expiry time of the first
  * timer (rounded to TIMER_GRANULARITY nanoseconds), and returns true.
+ *
+ * Example:
+ *     struct timespec next = { (time_t)-1ULL, -1UL };
+ *     timer_earliest(&timeouts, &next);
  */
 bool timer_earliest(struct timers *timers, struct timespec *first);
 
 /**
- * timer_expire - update timers structure and remove expired timers.
+ * timers_expire - update timers structure and remove expired timers.
  * @timers: the struct timers
  * @expire: the current time
  * @list: the list for expired timers.
@@ -84,6 +105,13 @@ bool timer_earliest(struct timers *timers, struct timespec *first);
  *
  * You should not move @expire backwards, though it need not move
  * forwards.
+ *
+ * Example:
+ *     struct list_head expired;
+ *
+ *     timers_expire(&timeouts, time_now(), &expired);
+ *     if (!list_empty(&expired))
+ *             printf("Timer expired!\n");
  */
 void timers_expire(struct timers *timers,
                   struct timespec expire,
@@ -101,6 +129,9 @@ void timers_expire(struct timers *timers,
  *
  * Returns the timers struct if it is consistent, NULL if not (it can
  * never return NULL if @abortstr is set).
+ *
+ * Example:
+ *     timers_check(&timeouts, "After timer_expire");
  */
 struct timers *timers_check(const struct timers *t, const char *abortstr);