git.ozlabs.org Git - ccan/blob - 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 one expire timer.
  93  * @timers: the struct timers
  94  * @expire: the current time
  95  *
  96  * A timers added with a @when arg less than or equal to @expire will be
  97  * returned (within TIMER_GRANULARITY nanosecond precision).  If
  98  * there are no timers due to expire, NULL is returned.
  99  *
 100  * After this returns NULL, @expire is considered the current time,
 101  * and adding any timers with @when before this value will be silently
 102  * changed to adding them with immediate expiration.
 103  *
 104  * You should not move @expire backwards, though it need not move
 105  * forwards.
 106  *
 107  * Example:
 108  *      struct timer *expired;
 109  *
 110  *      while ((expired = timers_expire(&timeouts, time_now())) != NULL)
 111  *              printf("Timer expired!\n");
 112  *
 113  */
 114 struct timer *timers_expire(struct timers *timers, struct timeabs expire);
 115
 116 /**
 117  * timers_check - check timer structure for consistency
 118  * @t: the struct timers
 119  * @abortstr: the location to print on aborting, or NULL.
 120  *
 121  * Because timers have redundant information, consistency checking can
 122  * be done on the tree.  This is useful as a debugging check.  If
 123  * @abortstr is non-NULL, that will be printed in a diagnostic if the
 124  * timers structure is inconsistent, and the function will abort.
 125  *
 126  * Returns the timers struct if it is consistent, NULL if not (it can
 127  * never return NULL if @abortstr is set).
 128  *
 129  * Example:
 130  *      timers_check(&timeouts, "After timer_expire");
 131  */
 132 struct timers *timers_check(const struct timers *t, const char *abortstr);
 133
 134 #ifdef CCAN_TIMER_DEBUG
 135 #include <stdio.h>
 136
 137 /**
 138  * timers_dump - dump the timers datastructure (for debugging it)
 139  * @t: the struct timers
 140  * @fp: the FILE to dump to (stderr if @fp is NULL)
 141  */
 142 void timers_dump(const struct timers *timers, FILE *fp);
 143 #endif
 144
 145 /**
 146  * struct timers - structure to hold a set of timers.
 147  *
 148  * Initialized using timers_init, the levels of the timer are
 149  * allocated as necessary, using malloc.
 150  *
 151  * See Also:
 152  *      timers_init(), timers_cleanup()
 153  */
 154 struct timers {
 155         /* Far in the future. */
 156         struct list_head far;
 157         uint64_t base;
 158         uint64_t first;
 159
 160         struct timer_level *level[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS];
 161 };
 162
 163 /**
 164  * struct timer - a single timer.
 165  *
 166  * Set up by timer_add(), this is usually contained within an
 167  * application-specific structure.
 168  *
 169  * See Also:
 170  *      ccan/container_of, timer_add(), timer_del()
 171  */
 172 struct timer {
 173         struct list_node list;
 174         uint64_t time;
 175 };
 176 #endif /* CCAN_TIMER_H */