git.ozlabs.org Git - ccan/blob - ccan/time/time.h

   1 #ifndef CCAN_TIME_H
   2 #define CCAN_TIME_H
   3 #include "config.h"
   4 #include <sys/time.h>
   5 #include <stdint.h>
   6 #include <stdbool.h>
   7
   8 /**
   9  * time_now - return the current time
  10  *
  11  * Example:
  12  *      printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
  13  */
  14 struct timeval time_now(void);
  15
  16 /**
  17  * time_greater - is a after b?
  18  * @a: one time.
  19  * @b: another time.
  20  *
  21  * Example:
  22  *      static bool timed_out(const struct timeval *start)
  23  *      {
  24  *      #define TIMEOUT time_from_msec(1000)
  25  *              return time_greater(time_now(), time_add(*start, TIMEOUT));
  26  *      }
  27  */
  28 bool time_greater(struct timeval a, struct timeval b);
  29
  30 /**
  31  * time_less - is a before b?
  32  * @a: one time.
  33  * @b: another time.
  34  *
  35  * Example:
  36  *      static bool still_valid(const struct timeval *start)
  37  *      {
  38  *      #define TIMEOUT time_from_msec(1000)
  39  *              return time_less(time_now(), time_add(*start, TIMEOUT));
  40  *      }
  41  */
  42 bool time_less(struct timeval a, struct timeval b);
  43
  44 /**
  45  * time_eq - is a equal to b?
  46  * @a: one time.
  47  * @b: another time.
  48  *
  49  * Example:
  50  *      #include <sys/types.h>
  51  *      #include <sys/wait.h>
  52  *
  53  *      // Can we fork in under a microsecond?
  54  *      static bool fast_fork(void)
  55  *      {
  56  *              struct timeval start = time_now();
  57  *              if (fork() != 0) {
  58  *                      exit(0);
  59  *              }
  60  *              wait(NULL);
  61  *              return time_eq(start, time_now());
  62  *      }
  63  */
  64 bool time_eq(struct timeval a, struct timeval b);
  65
  66 /**
  67  * time_sub - subtract two times
  68  * @recent: the larger (more recent) time.
  69  * @old: the smaller (less recent) time.
  70  *
  71  * This returns a well formed struct timeval.
  72  *
  73  * Example:
  74  *      static bool was_recent(const struct timeval *start)
  75  *      {
  76  *              return time_sub(time_now(), *start).tv_sec < 1;
  77  *      }
  78  */
  79 struct timeval time_sub(struct timeval recent, struct timeval old);
  80
  81 /**
  82  * time_add - add two times
  83  * @a: one time.
  84  * @b: another time.
  85  *
  86  * The times must not overflow, or the results are undefined.
  87  *
  88  * Example:
  89  *      // We do one every second.
  90  *      static struct timeval next_time(void)
  91  *      {
  92  *              return time_add(time_now(), time_from_msec(1000));
  93  *      }
  94  */
  95 struct timeval time_add(struct timeval a, struct timeval b);
  96
  97 /**
  98  * time_divide - divide a time by a value.
  99  * @t: a time.
 100  * @div: number to divide it by.
 101  *
 102  * Example:
 103  *      // How long does it take to do a fork?
 104  *      static struct timeval forking_time(void)
 105  *      {
 106  *              struct timeval start = time_now();
 107  *              unsigned int i;
 108  *
 109  *              for (i = 0; i < 1000; i++) {
 110  *                      if (fork() != 0) {
 111  *                              exit(0);
 112  *                      }
 113  *                      wait(NULL);
 114  *              }
 115  *              return time_divide(time_sub(time_now(), start), i);
 116  *      }
 117  */
 118 struct timeval time_divide(struct timeval t, unsigned long div);
 119
 120 /**
 121  * time_multiply - multiply a time by a value.
 122  * @t: a time.
 123  * @mult: number to multiply it by.
 124  *
 125  * Example:
 126  *      ...
 127  *      printf("Time to do 100000 forks would be %u sec\n",
 128  *             (unsigned)time_multiply(forking_time(), 1000000).tv_sec);
 129  */
 130 struct timeval time_multiply(struct timeval t, unsigned long mult);
 131
 132 /**
 133  * time_to_msec - return number of milliseconds
 134  * @t: a time
 135  *
 136  * It's often more convenient to deal with time values as
 137  * milliseconds.  Note that this will fit into a 32-bit variable if
 138  * it's a time difference of less than ~7 weeks.
 139  *
 140  * Example:
 141  *      ...
 142  *      printf("Forking time is %u msec\n",
 143  *             (unsigned)time_to_msec(forking_time()));
 144  */
 145 uint64_t time_to_msec(struct timeval t);
 146
 147 /**
 148  * time_to_usec - return number of microseconds
 149  * @t: a time
 150  *
 151  * It's often more convenient to deal with time values as
 152  * microseconds.  Note that this will fit into a 32-bit variable if
 153  * it's a time difference of less than ~1 hour.
 154  *
 155  * Example:
 156  *      ...
 157  *      printf("Forking time is %u usec\n",
 158  *             (unsigned)time_to_usec(forking_time()));
 159  *
 160  */
 161 uint64_t time_to_usec(struct timeval t);
 162
 163 /**
 164  * time_from_msec - convert milliseconds to a timeval
 165  * @msec: time in milliseconds
 166  *
 167  * Example:
 168  *      // 1/2 second timeout
 169  *      #define TIMEOUT time_from_msec(500)
 170  */
 171 struct timeval time_from_msec(uint64_t msec);
 172
 173 /**
 174  * time_from_usec - convert microseconds to a timeval
 175  * @usec: time in microseconds
 176  *
 177  * Example:
 178  *      // 1/2 second timeout
 179  *      #define TIMEOUT time_from_usec(500000)
 180  */
 181 struct timeval time_from_usec(uint64_t usec);
 182
 183 #endif /* CCAN_TIME_H */