io failtest timer tools: fallout from time changes.
[ccan] / ccan / timer / timer.h
1 /* LGPL (v2.1 or any later version) - see LICENSE file for details */
2 #ifndef CCAN_TIMER_H
3 #define CCAN_TIMER_H
4 #include <ccan/time/time.h>
5 #include <ccan/list/list.h>
6 #include <stdint.h>
7
8 #ifndef TIMER_GRANULARITY
9 /* We divide all nsec values by 1000, reducing it to usec granularity. */
10 #define TIMER_GRANULARITY 1000
11 #endif
12
13 #ifndef TIMER_LEVEL_BITS
14 /* This gives 32 pointers per level, up to 13 levels deep. */
15 #define TIMER_LEVEL_BITS 5
16 #endif
17
18 struct timers;
19 struct timer;
20
21 /**
22  * timers_init - initialize a timers struct.
23  * @timers: the struct timers
24  * @start: the minimum time which will ever be added.
25  *
26  * This sets up a timers struct: any timers added before @start will be
27  * set to expire immediately.
28  *
29  * Example:
30  *      struct timers timeouts;
31  *
32  *      timers_init(&timeouts, time_now());
33  */
34 void timers_init(struct timers *timers, struct timeabs start);
35
36 /**
37  * timers_cleanup - free allocations within timers struct.
38  * @timers: the struct timers
39  *
40  * This frees any timer layers allocated during use.
41  *
42  * Example:
43  *      timers_cleanup(&timeouts);
44  */
45 void timers_cleanup(struct timers *timers);
46
47 /**
48  * timer_add - insert a timer.
49  * @timers: the struct timers
50  * @timer: the (uninitialized) timer to add
51  * @when: when @timer expires.
52  *
53  * This efficiently adds @timer to @timers, to expire @when (rounded to
54  * TIMER_GRANULARITY nanoseconds).
55  *
56  * Example:
57  *      struct timer t;
58  *
59  *      // Timeout in 100ms.
60  *      timer_add(&timeouts, &t, timeabs_add(time_now(), time_from_msec(100)));
61  */
62 void timer_add(struct timers *timers, struct timer *timer, struct timeabs when);
63
64 /**
65  * timer_del - remove an unexpired timer.
66  * @timers: the struct timers
67  * @timer: the timer previously added with timer_add()
68  *
69  * This efficiently removes @timer from @timers.
70  *
71  * Example:
72  *      timer_del(&timeouts, &t);
73  */
74 void timer_del(struct timers *timers, struct timer *timer);
75
76 /**
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.
80  *
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.
84  *
85  * Example:
86  *      struct timeabs next = { { (time_t)-1ULL, -1UL } };
87  *      timer_earliest(&timeouts, &next);
88  */
89 bool timer_earliest(struct timers *timers, struct timeabs *first);
90
91 /**
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.
96  *
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).
100  *
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.
104  *
105  * You should not move @expire backwards, though it need not move
106  * forwards.
107  *
108  * Example:
109  *      struct list_head expired;
110  *
111  *      timers_expire(&timeouts, time_now(), &expired);
112  *      if (!list_empty(&expired))
113  *              printf("Timer expired!\n");
114  */
115 void timers_expire(struct timers *timers,
116                    struct timeabs expire,
117                    struct list_head *list);
118
119 /**
120  * timers_check - check timer structure for consistency
121  * @t: the struct timers
122  * @abortstr: the location to print on aborting, or NULL.
123  *
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.
128  *
129  * Returns the timers struct if it is consistent, NULL if not (it can
130  * never return NULL if @abortstr is set).
131  *
132  * Example:
133  *      timers_check(&timeouts, "After timer_expire");
134  */
135 struct timers *timers_check(const struct timers *t, const char *abortstr);
136
137 #ifdef CCAN_TIMER_DEBUG
138 #include <stdio.h>
139
140 /**
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)
144  */
145 void timers_dump(const struct timers *timers, FILE *fp);
146 #endif
147
148 /**
149  * struct timers - structure to hold a set of timers.
150  *
151  * Initialized using timers_init, the levels of the timer are
152  * allocated as necessary, using malloc.
153  *
154  * See Also:
155  *      timers_init(), timers_cleanup()
156  */
157 struct timers {
158         /* Far in the future. */
159         struct list_head far;
160         uint64_t base;
161         uint64_t first;
162
163         struct timer_level *level[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS];
164 };
165
166 /**
167  * struct timer - a single timer.
168  *
169  * Set up by timer_add(), this is usually contained within an
170  * application-specific structure.
171  *
172  * See Also:
173  *      ccan/container_of, timer_add(), timer_del()
174  */
175 struct timer {
176         struct list_node list;
177         uint64_t time;
178 };
179 #endif /* CCAN_TIMER_H */