X-Git-Url: https://git.ozlabs.org/?a=blobdiff_plain;f=ccan%2Ftimer%2Ftimer.h;h=e678f7f7dfcbf78274e89ecbefcdc8e320992f0b;hb=61c38f61b8a40dbd8fe48b7510e00cfcc5379378;hp=65f849b3dccc22743ed958a6d36ddb04370c2b65;hpb=996672df71a668d1ff7c650d0392c25250ab8dd8;p=ccan

diff --git a/ccan/timer/timer.h b/ccan/timer/timer.h
index 65f849b3..e678f7f7 100644
--- a/ccan/timer/timer.h
+++ b/ccan/timer/timer.h
@@ -25,69 +25,104 @@ 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);
+void timers_init(struct timers *timers, struct timeabs start);
 
 /**
  * timers_cleanup - free allocations within timers struct.
  * @timers: the struct timers
  *
  * This frees any timer layers allocated during use.
+ *
+ * Example:
+ *	timers_cleanup(&timeouts);
  */
 void timers_cleanup(struct timers *timers);
 
+/**
+ * timer_init - initialize a timer.
+ * @timer: the timer to initialize
+ *
+ * Example:
+ *	struct timer t;
+ *
+ *	timer_init(&t);
+ */
+void timer_init(struct timer *t);
+
 /**
  * timer_add - insert a timer.
  * @timers: the struct timers
- * @timer: the (uninitialized) timer to add
+ * @timer: the (initialized or timer_del'd) timer to add
  * @when: when @timer expires.
  *
  * This efficiently adds @timer to @timers, to expire @when (rounded to
  * TIMER_GRANULARITY nanoseconds).
+ *
+ * Example:
+ *	// Timeout in 100ms.
+ *	timer_add(&timeouts, &t, timeabs_add(time_now(), time_from_msec(100)));
  */
-void timer_add(struct timers *timers, struct timer *timer,
-	       struct timespec when);
+void timer_add(struct timers *timers, struct timer *timer, struct timeabs when);
 
 /**
- * timer_del - remove an unexpired timer.
+ * timer_del - remove a timer.
  * @timers: the struct timers
- * @timer: the timer previously added with timer_add()
+ * @timer: the timer
+ *
+ * This efficiently removes @timer from @timers, if timer_add() was
+ * called.  It can be called multiple times without bad effect, and
+ * can be called any time after timer_init().
  *
- * This efficiently removes @timer from @timers.
+ * Example:
+ *	timer_del(&timeouts, &t);
  */
 void timer_del(struct timers *timers, struct timer *timer);
 
 /**
  * timer_earliest - find out the first time when a timer will expire
  * @timers: the struct timers
- * @first: the time, only set if there is a timer.
+ * @first: the expiry time, only set if there is a 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 timeabs next = { { (time_t)-1ULL, -1UL } };
+ *	timer_earliest(&timeouts, &next);
  */
-bool timer_earliest(struct timers *timers, struct timespec *first);
+bool timer_earliest(struct timers *timers, struct timeabs *first);
 
 /**
- * timer_expire - update timers structure and remove expired timers.
+ * timers_expire - update timers structure and remove one expire timer.
  * @timers: the struct timers
  * @expire: the current time
- * @list: the list for expired timers.
  *
- * @list will be initialized to the empty list, then all timers added
- * with a @when arg less than or equal to @expire will be added to it in
- * expiry order (within TIMER_GRANULARITY nanosecond precision).
+ * A timers added with a @when arg less than or equal to @expire will be
+ * returned (within TIMER_GRANULARITY nanosecond precision).  If
+ * there are no timers due to expire, NULL is returned.
  *
- * After this, @expire is considered the current time, and adding any
- * timers with @when before this value will be silently changed to
- * adding them with immediate expiration.
+ * After this returns NULL, @expire is considered the current time,
+ * and adding any timers with @when before this value will be silently
+ * changed to adding them with immediate expiration.
  *
  * You should not move @expire backwards, though it need not move
  * forwards.
+ *
+ * Example:
+ *	struct timer *expired;
+ *
+ *	while ((expired = timers_expire(&timeouts, time_now())) != NULL)
+ *		printf("Timer expired!\n");
+ *
  */
-void timers_expire(struct timers *timers,
-		   struct timespec expire,
-		   struct list_head *list);
+struct timer *timers_expire(struct timers *timers, struct timeabs expire);
 
 /**
  * timers_check - check timer structure for consistency
@@ -101,6 +136,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);
 
@@ -127,8 +165,12 @@ void timers_dump(const struct timers *timers, FILE *fp);
 struct timers {
 	/* Far in the future. */
 	struct list_head far;
+	/* Current time. */
 	uint64_t base;
+	/* Overall first value. */
 	uint64_t first;
+	/* First value in each level (plus 1 for far list) */
+	uint64_t firsts[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS + 1];
 
 	struct timer_level *level[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS];
 };