X-Git-Url: http://git.ozlabs.org/?p=ccan;a=blobdiff_plain;f=ccan%2Ftimer%2Ftimer.h;h=79399cc4e0e006fe7b455dc0cff20890130bea5f;hp=3bf28d0fbda2cdd8f4e3396bc19928d2b1ac7960;hb=daf9ee7d8e2b683ff05283beb1843611ad8c9e8a;hpb=a40fc5a89e5336f405b84387d387c9f5a74e95fa

diff --git a/ccan/timer/timer.h b/ccan/timer/timer.h
index 3bf28d0f..79399cc4 100644
--- a/ccan/timer/timer.h
+++ b/ccan/timer/timer.h
@@ -5,10 +5,15 @@
 #include <ccan/list/list.h>
 #include <stdint.h>
 
+#ifndef TIMER_GRANULARITY
 /* We divide all nsec values by 1000, reducing it to usec granularity. */
 #define TIMER_GRANULARITY 1000
-/* This gives 16 pointers per level, up to 13 levels deep. */
-#define TIMER_LEVEL_BITS 4
+#endif
+
+#ifndef TIMER_LEVEL_BITS
+/* This gives 32 pointers per level, up to 13 levels deep. */
+#define TIMER_LEVEL_BITS 5
+#endif
 
 struct timers;
 struct timer;
@@ -20,14 +25,22 @@ 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);
 
@@ -39,9 +52,14 @@ 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, 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.
@@ -49,22 +67,29 @@ 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);
 
 /**
  * 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 expired timers.
  * @timers: the struct timers
  * @expire: the current time
  * @list: the list for expired timers.
@@ -79,9 +104,16 @@ 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,
+		   struct timeabs expire,
 		   struct list_head *list);
 
 /**
@@ -96,6 +128,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);