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 /* We divide all nsec values by 1000, reducing it to usec granularity. */
   9 #define TIMER_GRANULARITY 1000
  10 /* This gives 16 pointers per level, up to 13 levels deep. */
  11 #define TIMER_LEVEL_BITS 4
  12
  13 struct timers;
  14 struct timer;
  15
  16 /**
  17  * timers_init - initialize a timers struct.
  18  * @timers: the struct timers
  19  * @start: the minimum time which will ever be added.
  20  *
  21  * This sets up a timers struct: any timers added before @start will be
  22  * set to expire immediately.
  23  */
  24 void timers_init(struct timers *timers, struct timespec start);
  25
  26 /**
  27  * timers_cleanup - free allocations within timers struct.
  28  * @timers: the struct timers
  29  *
  30  * This frees any timer layers allocated during use.
  31  */
  32 void timers_cleanup(struct timers *timers);
  33
  34 /**
  35  * timer_add - insert a timer.
  36  * @timers: the struct timers
  37  * @timer: the (uninitialized) timer to add
  38  * @when: when @timer expires.
  39  *
  40  * This efficiently adds @timer to @timers, to expire @when (rounded to
  41  * TIMER_GRANULARITY nanoseconds).
  42  */
  43 void timer_add(struct timers *timers, struct timer *timer,
  44                struct timespec when);
  45
  46 /**
  47  * timer_del - remove an unexpired timer.
  48  * @timers: the struct timers
  49  * @timer: the timer previously added with timer_add()
  50  *
  51  * This efficiently removes @timer from @timers.
  52  */
  53 void timer_del(struct timers *timers, struct timer *timer);
  54
  55 /**
  56  * timer_earliest - find out the first time when a timer will expire
  57  * @timers: the struct timers
  58  * @first: the time, only set if there is a timer.
  59  *
  60  * This returns false, and doesn't alter @first if there are no
  61  * timers.  Otherwise, it sets @first to the expiry time of the first
  62  * timer (rounded to TIMER_GRANULARITY nanoseconds), and returns true.
  63  */
  64 bool timer_earliest(struct timers *timers, struct timespec *first);
  65
  66 /**
  67  * timer_expire - update timers structure and remove expired timers.
  68  * @timers: the struct timers
  69  * @expire: the current time
  70  * @list: the list for expired timers.
  71  *
  72  * @list will be initialized to the empty list, then all timers added
  73  * with a @when arg less than or equal to @expire will be added to it in
  74  * expiry order (within TIMER_GRANULARITY nanosecond precision).
  75  *
  76  * After this, @expire is considered the current time, and adding any
  77  * timers with @when before this value will be silently changed to
  78  * adding them with immediate expiration.
  79  *
  80  * You should not move @expire backwards, though it need not move
  81  * forwards.
  82  */
  83 void timers_expire(struct timers *timers,
  84                    struct timespec expire,
  85                    struct list_head *list);
  86
  87 /**
  88  * timers_check - check timer structure for consistency
  89  * @t: the struct timers
  90  * @abortstr: the location to print on aborting, or NULL.
  91  *
  92  * Because timers have redundant information, consistency checking can
  93  * be done on the tree.  This is useful as a debugging check.  If
  94  * @abortstr is non-NULL, that will be printed in a diagnostic if the
  95  * timers structure is inconsistent, and the function will abort.
  96  *
  97  * Returns the timers struct if it is consistent, NULL if not (it can
  98  * never return NULL if @abortstr is set).
  99  */
 100 struct timers *timers_check(const struct timers *t, const char *abortstr);
 101
 102 #ifdef CCAN_TIMER_DEBUG
 103 #include <stdio.h>
 104
 105 /**
 106  * timers_dump - dump the timers datastructure (for debugging it)
 107  * @t: the struct timers
 108  * @fp: the FILE to dump to (stderr if @fp is NULL)
 109  */
 110 void timers_dump(const struct timers *timers, FILE *fp);
 111 #endif
 112
 113 /**
 114  * struct timers - structure to hold a set of timers.
 115  *
 116  * Initialized using timers_init, the levels of the timer are
 117  * allocated as necessary, using malloc.
 118  *
 119  * See Also:
 120  *      timers_init(), timers_cleanup()
 121  */
 122 struct timers {
 123         /* Far in the future. */
 124         struct list_head far;
 125         uint64_t base;
 126         uint64_t first;
 127
 128         struct timer_level *level[(64 + TIMER_LEVEL_BITS-1) / TIMER_LEVEL_BITS];
 129 };
 130
 131 /**
 132  * struct timer - a single timer.
 133  *
 134  * Set up by timer_add(), this is usually contained within an
 135  * application-specific structure.
 136  *
 137  * See Also:
 138  *      ccan/container_of, timer_add(), timer_del()
 139  */
 140 struct timer {
 141         struct list_node list;
 142         uint64_t time;
 143 };
 144 #endif /* CCAN_TIMER_H */