* @when: when @timer expires.
*
* This efficiently adds @timer to @timers, to expire @when (rounded to
* TIMER_GRANULARITY nanoseconds).
*
* Example:
* @when: when @timer expires.
*
* This efficiently adds @timer to @timers, to expire @when (rounded to
* TIMER_GRANULARITY nanoseconds).
*
* Example:
- * timer_add(&timeouts, &t, time_add(time_now(), time_from_msec(100)));
+ * timer_add(&timeouts, &t, timeabs_add(time_now(), time_from_msec(100)));
- * This efficiently removes @timer from @timers.
+ * 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 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:
*
* 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:
- * @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.
- * timers_expire(&timeouts, time_now(), &expired);
- * if (!list_empty(&expired))
+ * while ((expired = timers_expire(&timeouts, time_now())) != NULL)
-void timers_expire(struct timers *timers,
- struct timespec expire,
- struct list_head *list);
+struct timer *timers_expire(struct timers *timers, struct timeabs expire);