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_now());
34 void timers_init(struct timers *timers, struct timeabs 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_add - insert a timer.
49 * @timers: the struct timers
50 * @timer: the (uninitialized) timer to add
51 * @when: when @timer expires.
53 * This efficiently adds @timer to @timers, to expire @when (rounded to
54 * TIMER_GRANULARITY nanoseconds).
59 * // Timeout in 100ms.
60 * timer_add(&timeouts, &t, timeabs_add(time_now(), time_from_msec(100)));
62 void timer_add(struct timers *timers, struct timer *timer, struct timeabs when);
65 * timer_del - remove an unexpired timer.
66 * @timers: the struct timers
67 * @timer: the timer previously added with timer_add()
69 * This efficiently removes @timer from @timers.
72 * timer_del(&timeouts, &t);
74 void timer_del(struct timers *timers, struct timer *timer);
77 * timer_earliest - find out the first time when a timer will expire
78 * @timers: the struct timers
79 * @first: the expiry time, only set if there is a timer.
81 * This returns false, and doesn't alter @first if there are no
82 * timers. Otherwise, it sets @first to the expiry time of the first
83 * timer (rounded to TIMER_GRANULARITY nanoseconds), and returns true.
86 * struct timeabs next = { { (time_t)-1ULL, -1UL } };
87 * timer_earliest(&timeouts, &next);
89 bool timer_earliest(struct timers *timers, struct timeabs *first);
92 * timers_expire - update timers structure and remove expired timers.
93 * @timers: the struct timers
94 * @expire: the current time
95 * @list: the list for expired timers.
97 * @list will be initialized to the empty list, then all timers added
98 * with a @when arg less than or equal to @expire will be added to it in
99 * expiry order (within TIMER_GRANULARITY nanosecond precision).
101 * After this, @expire is considered the current time, and adding any
102 * timers with @when before this value will be silently changed to
103 * adding them with immediate expiration.
105 * You should not move @expire backwards, though it need not move
109 * struct list_head expired;
111 * timers_expire(&timeouts, time_now(), &expired);
112 * if (!list_empty(&expired))
113 * printf("Timer expired!\n");
115 void timers_expire(struct timers *timers,
116 struct timeabs expire,
117 struct list_head *list);
120 * timers_check - check timer structure for consistency
121 * @t: the struct timers
122 * @abortstr: the location to print on aborting, or NULL.
124 * Because timers have redundant information, consistency checking can
125 * be done on the tree. This is useful as a debugging check. If
126 * @abortstr is non-NULL, that will be printed in a diagnostic if the
127 * timers structure is inconsistent, and the function will abort.
129 * Returns the timers struct if it is consistent, NULL if not (it can
130 * never return NULL if @abortstr is set).
133 * timers_check(&timeouts, "After timer_expire");
135 struct timers *timers_check(const struct timers *t, const char *abortstr);
137 #ifdef CCAN_TIMER_DEBUG
141 * timers_dump - dump the timers datastructure (for debugging it)
142 * @t: the struct timers
143 * @fp: the FILE to dump to (stderr if @fp is NULL)
145 void timers_dump(const struct timers *timers, FILE *fp);
149 * struct timers - structure to hold a set of timers.
151 * Initialized using timers_init, the levels of the timer are
152 * allocated as necessary, using malloc.
155 * timers_init(), timers_cleanup()
158 /* Far in the future. */
159 struct list_head far;
163 struct timer_level *level[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS];
167 * struct timer - a single timer.
169 * Set up by timer_add(), this is usually contained within an
170 * application-specific structure.
173 * ccan/container_of, timer_add(), timer_del()
176 struct list_node list;
179 #endif /* CCAN_TIMER_H */