X-Git-Url: http://git.ozlabs.org/?a=blobdiff_plain;f=ccan%2Ftimer%2Ftimer.h;h=79399cc4e0e006fe7b455dc0cff20890130bea5f;hb=806f94eb6c0c3eb521458901a23e470037ede807;hp=65f849b3dccc22743ed958a6d36ddb04370c2b65;hpb=996672df71a668d1ff7c650d0392c25250ab8dd8;p=ccan diff --git a/ccan/timer/timer.h b/ccan/timer/timer.h index 65f849b3..79399cc4 100644 --- a/ccan/timer/timer.h +++ b/ccan/timer/timer.h @@ -25,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); @@ -44,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. @@ -54,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. @@ -84,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); /** @@ -101,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);