time: new module for dealing with time.
[ccan] / 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 */