lib/ccan/time/time.h

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