1 /* LGPL (v2.1 or any later version) - see LICENSE file for details */
4 #include <ccan/time/time.h>
5 #include <ccan/list/list.h>
8 #ifndef TIMER_GRANULARITY
9 /* We divide all nsec values by 1000, reducing it to usec granularity. */
10 #define TIMER_GRANULARITY 1000
13 #ifndef TIMER_LEVEL_BITS
14 /* This gives 32 pointers per level, up to 13 levels deep. */
15 #define TIMER_LEVEL_BITS 5
22 * timers_init - initialize a timers struct.
23 * @timers: the struct timers
24 * @start: the minimum time which will ever be added.
26 * This sets up a timers struct: any timers added before @start will be
27 * set to expire immediately.
30 * struct timers timeouts;
32 * timers_init(&timeouts, time_mono());
34 void timers_init(struct timers *timers, struct timemono start);
37 * timers_cleanup - free allocations within timers struct.
38 * @timers: the struct timers
40 * This frees any timer layers allocated during use.
43 * timers_cleanup(&timeouts);
45 void timers_cleanup(struct timers *timers);
48 * timer_init - initialize a timer.
49 * @timer: the timer to initialize
56 void timer_init(struct timer *t);
59 * timer_addrel - insert a relative timer.
60 * @timers: the struct timers
61 * @timer: the (initialized or timer_del'd) timer to add
62 * @rel: when @timer expires (relative).
64 * This efficiently adds @timer to @timers, to expire @rel (rounded to
65 * TIMER_GRANULARITY nanoseconds) after the current time. This
66 * is a convenient wrapper around timer_addmono().
69 * // Timeout in 100ms.
70 * timer_addrel(&timeouts, &t, time_from_msec(100));
72 void timer_addrel(struct timers *timers, struct timer *timer, struct timerel rel);
75 * timer_addmono - insert an absolute timer.
76 * @timers: the struct timers
77 * @timer: the (initialized or timer_del'd) timer to add
78 * @when: when @timer expires (absolute).
80 * This efficiently adds @timer to @timers, to expire @when (rounded to
81 * TIMER_GRANULARITY nanoseconds).
83 * Note that if @when is before time_mono(), then it will be set to expire
87 * // Timeout in 100ms.
88 * timer_addmono(&timeouts, &t, timemono_add(time_mono(), time_from_msec(100)));
90 void timer_addmono(struct timers *timers, struct timer *timer,
91 struct timemono when);
94 * timer_del - remove a timer.
95 * @timers: the struct timers
98 * This efficiently removes @timer from @timers, if timer_add() was
99 * called. It can be called multiple times without bad effect, and
100 * can be called any time after timer_init().
103 * timer_del(&timeouts, &t);
105 void timer_del(struct timers *timers, struct timer *timer);
108 * timer_earliest - find out the first time when a timer will expire
109 * @timers: the struct timers
110 * @first: the expiry time, only set if there is a timer.
112 * This returns false, and doesn't alter @first if there are no
113 * timers. Otherwise, it sets @first to the expiry time of the first
114 * timer (rounded to TIMER_GRANULARITY nanoseconds), and returns true.
117 * struct timemono next = { { (time_t)-1ULL, -1UL } };
118 * timer_earliest(&timeouts, &next);
120 bool timer_earliest(struct timers *timers, struct timemono *first);
123 * timers_expire - update timers structure and remove one expire timer.
124 * @timers: the struct timers
125 * @expire: the current time
127 * A timers added with a @when arg less than or equal to @expire will be
128 * returned (within TIMER_GRANULARITY nanosecond precision). If
129 * there are no timers due to expire, NULL is returned.
131 * After this returns NULL, @expire is considered the current time,
132 * and adding any timers with @when before this value will be silently
133 * changed to adding them with immediate expiration.
135 * You should not move @expire backwards, though it need not move
139 * struct timer *expired;
141 * while ((expired = timers_expire(&timeouts, time_mono())) != NULL)
142 * printf("Timer expired!\n");
145 struct timer *timers_expire(struct timers *timers, struct timemono expire);
148 * timers_check - check timer structure for consistency
149 * @t: the struct timers
150 * @abortstr: the location to print on aborting, or NULL.
152 * Because timers have redundant information, consistency checking can
153 * be done on the tree. This is useful as a debugging check. If
154 * @abortstr is non-NULL, that will be printed in a diagnostic if the
155 * timers structure is inconsistent, and the function will abort.
157 * Returns the timers struct if it is consistent, NULL if not (it can
158 * never return NULL if @abortstr is set).
161 * timers_check(&timeouts, "After timer_expire");
163 struct timers *timers_check(const struct timers *t, const char *abortstr);
165 #ifdef CCAN_TIMER_DEBUG
169 * timers_dump - dump the timers datastructure (for debugging it)
170 * @t: the struct timers
171 * @fp: the FILE to dump to (stderr if @fp is NULL)
173 void timers_dump(const struct timers *timers, FILE *fp);
177 * struct timers - structure to hold a set of timers.
179 * Initialized using timers_init, the levels of the timer are
180 * allocated as necessary, using malloc.
183 * timers_init(), timers_cleanup()
186 /* Far in the future. */
187 struct list_head far;
190 /* Overall first value. */
192 /* First value in each level (plus 1 for far list) */
193 uint64_t firsts[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS + 1];
195 struct timer_level *level[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS];
199 * struct timer - a single timer.
201 * Set up by timer_add(), this is usually contained within an
202 * application-specific structure.
205 * ccan/container_of, timer_add(), timer_del()
208 struct list_node list;
211 #endif /* CCAN_TIMER_H */