fb2ee459d694a99c40f31efcbacc1530c549eeed
[ccan] / 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 */