time: timemono_add.
[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 #if HAVE_STRUCT_TIMESPEC
7 #include <time.h>
8 #else
9 struct timespec {
10         time_t   tv_sec;        /* seconds */
11         long     tv_nsec;       /* nanoseconds */
12 };
13 #endif
14 #include <stdint.h>
15 #include <stdbool.h>
16
17 #ifdef DEBUG
18 #include <ccan/str/str.h>
19 #define TIME_CHECK(t) \
20         time_check_((t), __FILE__ ":" stringify(__LINE__) " (" stringify(t) ") ")
21 #define TIMEREL_CHECK(t) \
22         timerel_check((t), __FILE__ ":" stringify(__LINE__) " (" stringify(t) ") ")
23 #define TIMEABS_CHECK(t) \
24         timeabs_check((t), __FILE__ ":" stringify(__LINE__) " (" stringify(t) ") ")
25 #else
26 #define TIME_CHECK(t) (t)
27 #define TIMEREL_CHECK(t) (t)
28 #define TIMEABS_CHECK(t) (t)
29 #endif
30
31 /**
32  * struct timerel - a relative time.
33  * @ts: the actual timespec value.
34  *
35  * For example, 1 second: ts.tv_sec = 1, ts.tv_nsec = 0
36  */
37 struct timerel {
38         struct timespec ts;
39 };
40
41 /**
42  * struct timeabs - an absolue time.
43  * @ts: the actual timespec value.
44  *
45  * For example, Midnight UTC January 1st, 1970: ts.tv_sec = 0, ts.tv_nsec = 0
46  */
47 struct timeabs {
48         struct timespec ts;
49 };
50
51 /**
52  * struct timemono - a monotonic time.
53  * @ts: the actual timespec value.
54  *
55  * This comes from the monotonic clock (if available), so it's useful
56  * for measuring intervals as it won't change even if the system clock
57  * is moved for some reason.
58  */
59 struct timemono {
60         struct timespec ts;
61 };
62
63 /**
64  * TIME_HAVE_MONOTONIC - defined if we really have a monotonic clock.
65  *
66  * Otherwise time_mono() just refers to time_now().  Your code might
67  * test this if you really need a monotonic clock.
68  */
69 #if HAVE_CLOCK_GETTIME && defined(CLOCK_MONOTONIC)
70 #define TIME_HAVE_MONOTONIC 1
71 #endif
72
73 struct timespec time_check_(struct timespec in, const char *abortstr);
74
75 /**
76  * timerel_check - check if a relative time is malformed.
77  * @in: the relative time to check (returned)
78  * @abortstr: the string to print to stderr before aborting (if set).
79  *
80  * This can be used to make sure a time isn't negative and doesn't
81  * have a tv_nsec >= 1000000000.  If it is, and @abortstr is non-NULL,
82  * that will be printed and abort() is called.  Otherwise, if
83  * @abortstr is NULL then the returned timerel will be normalized and
84  * tv_sec set to 0 if it was negative.
85  *
86  * Note that if ccan/time is compiled with DEBUG, then it will call this
87  * for all passed and returned times.
88  *
89  * Example:
90  *      printf("Time to calc this was %lu nanoseconds\n",
91  *              (long)timerel_check(time_between(time_now(), time_now()),
92  *                                  "time_now() failed?").ts.tv_nsec);
93  */
94 struct timerel timerel_check(struct timerel in, const char *abortstr);
95
96 /**
97  * timeabs_check - check if an absolute time is malformed.
98  * @in: the relative time to check (returned)
99  * @abortstr: the string to print to stderr before aborting (if set).
100  *
101  * This can be used to make sure a time isn't negative and doesn't
102  * have a tv_nsec >= 1000000000.  If it is, and @abortstr is non-NULL,
103  * that will be printed and abort() is called.  Otherwise, if
104  * @abortstr is NULL then the returned timeabs will be normalized and
105  * tv_sec set to 0 if it was negative.
106  *
107  * Note that if ccan/time is compiled with DEBUG, then it will call this
108  * for all passed and returned times.
109  *
110  * Example:
111  *      printf("Now is %lu seconds since epoch\n",
112  *              (long)timeabs_check(time_now(), "time_now failed?").ts.tv_sec);
113  */
114 struct timeabs timeabs_check(struct timeabs in, const char *abortstr);
115
116 /**
117  * time_now - return the current time
118  *
119  * Example:
120  *      printf("Now is %lu seconds since epoch\n", (long)time_now().ts.tv_sec);
121  */
122 struct timeabs time_now(void);
123
124 /**
125  * time_mono - return the current monotonic time
126  *
127  * This value is only really useful for measuring time intervals.
128  *
129  * See also:
130  *      timemono_since()
131  */
132 struct timemono time_mono(void);
133
134 static inline bool time_greater_(struct timespec a, struct timespec b)
135 {
136         if (TIME_CHECK(a).tv_sec > TIME_CHECK(b).tv_sec)
137                 return true;
138         else if (a.tv_sec < b.tv_sec)
139                  return false;
140
141         return a.tv_nsec > b.tv_nsec;
142 }
143
144 /**
145  * time_after - is a after b?
146  * @a: one abstime.
147  * @b: another abstime.
148  *
149  * Example:
150  *      static bool timed_out(const struct timeabs *start)
151  *      {
152  *      #define TIMEOUT time_from_msec(1000)
153  *              return time_after(time_now(), timeabs_add(*start, TIMEOUT));
154  *      }
155  */
156 static inline bool time_after(struct timeabs a, struct timeabs b)
157 {
158         return time_greater_(a.ts, b.ts);
159 }
160
161 /**
162  * time_greater - is a greater than b?
163  * @a: one reltime.
164  * @b: another reltime.
165  */
166 static inline bool time_greater(struct timerel a, struct timerel b)
167 {
168         return time_greater_(a.ts, b.ts);
169 }
170
171 static inline bool time_less_(struct timespec a, struct timespec b)
172 {
173         if (TIME_CHECK(a).tv_sec < TIME_CHECK(b).tv_sec)
174                 return true;
175         else if (a.tv_sec > b.tv_sec)
176                  return false;
177
178         return a.tv_nsec < b.tv_nsec;
179 }
180
181 /**
182  * time_before - is a before b?
183  * @a: one absolute time.
184  * @b: another absolute time.
185  *
186  * Example:
187  *      static bool still_valid(const struct timeabs *start)
188  *      {
189  *      #define TIMEOUT time_from_msec(1000)
190  *              return time_before(time_now(), timeabs_add(*start, TIMEOUT));
191  *      }
192  */
193 static inline bool time_before(struct timeabs a, struct timeabs b)
194 {
195         return time_less_(a.ts, b.ts);
196 }
197
198 /**
199  * time_less - is a before b?
200  * @a: one relative time.
201  * @b: another relative time.
202  */
203 static inline bool time_less(struct timerel a, struct timerel b)
204 {
205         return time_less_(a.ts, b.ts);
206 }
207
208 /**
209  * timeabs_eq - is a equal to b?
210  * @a: one absolute time.
211  * @b: another absolute time.
212  *
213  * Example:
214  *      #include <sys/types.h>
215  *      #include <sys/wait.h>
216  *
217  *      // Can we fork in under a nanosecond?
218  *      static bool fast_fork(void)
219  *      {
220  *              struct timeabs start = time_now();
221  *              if (fork() != 0) {
222  *                      exit(0);
223  *              }
224  *              wait(NULL);
225  *              return timeabs_eq(start, time_now());
226  *      }
227  */
228 static inline bool timeabs_eq(struct timeabs a, struct timeabs b)
229 {
230         return TIMEABS_CHECK(a).ts.tv_sec == TIMEABS_CHECK(b).ts.tv_sec
231                 && a.ts.tv_nsec == b.ts.tv_nsec;
232 }
233
234 /**
235  * timerel_eq - is a equal to b?
236  * @a: one relative time.
237  * @b: another relative time.
238  *
239  * Example:
240  *      #include <sys/types.h>
241  *      #include <sys/wait.h>
242  *
243  *      // Can we fork in under a nanosecond?
244  *      static bool fast_fork(void)
245  *      {
246  *              struct timeabs start = time_now();
247  *              struct timerel diff, zero = { .ts = { 0, 0 } };
248  *              if (fork() != 0) {
249  *                      exit(0);
250  *              }
251  *              wait(NULL);
252  *              diff = time_between(time_now(), start);
253  *              return timerel_eq(diff, zero);
254  *      }
255  */
256 static inline bool timerel_eq(struct timerel a, struct timerel b)
257 {
258         return TIMEREL_CHECK(a).ts.tv_sec == TIMEREL_CHECK(b).ts.tv_sec
259                 && a.ts.tv_nsec == b.ts.tv_nsec;
260 }
261
262 static inline struct timespec time_sub_(struct timespec recent,
263                                         struct timespec old)
264 {
265         struct timespec diff;
266
267         diff.tv_sec = TIME_CHECK(recent).tv_sec - TIME_CHECK(old).tv_sec;
268         if (old.tv_nsec > recent.tv_nsec) {
269                 diff.tv_sec--;
270                 diff.tv_nsec = 1000000000 + recent.tv_nsec - old.tv_nsec;
271         } else
272                 diff.tv_nsec = recent.tv_nsec - old.tv_nsec;
273
274         return TIME_CHECK(diff);
275 }
276
277 /**
278  * time_sub - subtract two relative times
279  * @a: the larger time.
280  * @b: the smaller time.
281  *
282  * This returns a well formed struct timerel of @a - @b.
283  */
284 static inline struct timerel time_sub(struct timerel a, struct timerel b)
285 {
286         struct timerel t;
287
288         t.ts = time_sub_(a.ts, b.ts);
289         return t;
290 }
291
292 /**
293  * time_between - time between two absolute times
294  * @recent: the larger time.
295  * @old: the smaller time.
296  *
297  * This returns a well formed struct timerel of @a - @b.
298  */
299 static inline struct timerel time_between(struct timeabs recent, struct timeabs old)
300 {
301         struct timerel t;
302
303         t.ts = time_sub_(recent.ts, old.ts);
304         return t;
305 }
306
307 /**
308  * timemono_between - time between two monotonic times
309  * @recent: the larger time.
310  * @old: the smaller time.
311  *
312  * This returns a well formed struct timerel of @recent - @old.
313  */
314 static inline struct timerel timemono_between(struct timemono recent,
315                                               struct timemono old)
316 {
317         struct timerel t;
318
319         t.ts = time_sub_(recent.ts, old.ts);
320         return t;
321 }
322
323 /**
324  * timemono_since - elapsed monotonic time since @old
325  * @old: a monotonic time from the past.
326  */
327 static inline struct timerel timemono_since(struct timemono old)
328 {
329         struct timemono now = time_mono();
330
331         return timemono_between(now, old);
332 }
333
334 /**
335  * timeabs_sub - subtract a relative time from an absolute time
336  * @abs: the absolute time.
337  * @rel: the relative time.
338  *
339  * This returns a well formed struct timeabs of @a - @b.
340  *
341  * Example:
342  *      // We do one every second.
343  *      static struct timeabs previous_time(void)
344  *      {
345  *              return timeabs_sub(time_now(), time_from_msec(1000));
346  *      }
347  */
348 static inline struct timeabs timeabs_sub(struct timeabs abs, struct timerel rel)
349 {
350         struct timeabs t;
351
352         t.ts = time_sub_(abs.ts, rel.ts);
353         return t;
354 }
355
356 static inline struct timespec time_add_(struct timespec a, struct timespec b)
357 {
358         struct timespec sum;
359
360         sum.tv_sec = TIME_CHECK(a).tv_sec + TIME_CHECK(b).tv_sec;
361         sum.tv_nsec = a.tv_nsec + b.tv_nsec;
362         if (sum.tv_nsec >= 1000000000) {
363                 sum.tv_sec++;
364                 sum.tv_nsec -= 1000000000;
365         }
366         return TIME_CHECK(sum);
367 }
368
369 /**
370  * timeabs_add - add a relative to an absolute time
371  * @a: the absolute time.
372  * @b: a relative time.
373  *
374  * The times must not overflow, or the results are undefined.
375  *
376  * Example:
377  *      // We do one every second.
378  *      static struct timeabs next_time(void)
379  *      {
380  *              return timeabs_add(time_now(), time_from_msec(1000));
381  *      }
382  */
383 static inline struct timeabs timeabs_add(struct timeabs a, struct timerel b)
384 {
385         struct timeabs t;
386
387         t.ts = time_add_(a.ts, b.ts);
388         return t;
389 }
390
391 /**
392  * timemono_add - add a relative to a monotonic time
393  * @a: the monotonic time.
394  * @b: a relative time.
395  *
396  * The times must not overflow, or the results are undefined.
397  *
398  * Example:
399  *      // We do one every second.
400  *      static struct timemono next_timem(void)
401  *      {
402  *              return timemono_add(time_mono(), time_from_msec(1000));
403  *      }
404  */
405 static inline struct timemono timemono_add(struct timemono a, struct timerel b)
406 {
407         struct timemono t;
408
409         t.ts = time_add_(a.ts, b.ts);
410         return t;
411 }
412
413 /**
414  * timerel_add - add two relative times
415  * @a: one relative time.
416  * @b: another relative time.
417  *
418  * The times must not overflow, or the results are undefined.
419  *
420  * Example:
421  *      static struct timerel double_time(struct timerel a)
422  *      {
423  *              return timerel_add(a, a);
424  *      }
425  */
426 static inline struct timerel timerel_add(struct timerel a, struct timerel b)
427 {
428         struct timerel t;
429
430         t.ts = time_add_(a.ts, b.ts);
431         return t;
432 }
433
434 /**
435  * time_divide - divide a time by a value.
436  * @t: a time.
437  * @div: number to divide it by.
438  *
439  * Example:
440  *      // How long does it take to do a fork?
441  *      static struct timerel forking_time(void)
442  *      {
443  *              struct timeabs start = time_now();
444  *              unsigned int i;
445  *
446  *              for (i = 0; i < 1000; i++) {
447  *                      if (fork() != 0) {
448  *                              exit(0);
449  *                      }
450  *                      wait(NULL);
451  *              }
452  *              return time_divide(time_between(time_now(), start), i);
453  *      }
454  */
455 struct timerel time_divide(struct timerel t, unsigned long div);
456
457 /**
458  * time_multiply - multiply a time by a value.
459  * @t: a relative time.
460  * @mult: number to multiply it by.
461  *
462  * Example:
463  *      ...
464  *      printf("Time to do 100000 forks would be %u sec\n",
465  *             (unsigned)time_multiply(forking_time(), 1000000).ts.tv_sec);
466  */
467 struct timerel time_multiply(struct timerel t, unsigned long mult);
468
469 /**
470  * time_to_sec - return number of seconds
471  * @t: a time
472  *
473  * It's often more convenient to deal with time values as seconds.
474  * Note that this will fit into an unsigned 32-bit variable if it's a
475  * time of less than about 136 years.
476  *
477  * Example:
478  *      ...
479  *      printf("Forking time is %u sec\n",
480  *             (unsigned)time_to_sec(forking_time()));
481  */
482 static inline uint64_t time_to_sec(struct timerel t)
483 {
484         return t.ts.tv_sec;
485 }
486
487 /**
488  * time_to_msec - return number of milliseconds
489  * @t: a relative time
490  *
491  * It's often more convenient to deal with time values as
492  * milliseconds.  Note that this will fit into a 32-bit variable if
493  * it's a time difference of less than ~7 weeks.
494  *
495  * Example:
496  *      ...
497  *      printf("Forking time is %u msec\n",
498  *             (unsigned)time_to_msec(forking_time()));
499  */
500 static inline uint64_t time_to_msec(struct timerel t)
501 {
502         uint64_t msec;
503
504         msec = TIMEREL_CHECK(t).ts.tv_nsec/1000000 + (uint64_t)t.ts.tv_sec*1000;
505         return msec;
506 }
507
508 /**
509  * time_to_usec - return number of microseconds
510  * @t: a relative time
511  *
512  * It's often more convenient to deal with time values as
513  * microseconds.  Note that this will fit into a 32-bit variable if
514  * it's a time difference of less than ~1 hour.
515  *
516  * Example:
517  *      ...
518  *      printf("Forking time is %u usec\n",
519  *             (unsigned)time_to_usec(forking_time()));
520  *
521  */
522 static inline uint64_t time_to_usec(struct timerel t)
523 {
524         uint64_t usec;
525
526         usec = TIMEREL_CHECK(t).ts.tv_nsec/1000 + (uint64_t)t.ts.tv_sec*1000000;
527         return usec;
528 }
529
530 /**
531  * time_to_nsec - return number of nanoseconds
532  * @t: a relative time
533  *
534  * It's sometimes more convenient to deal with time values as
535  * nanoseconds.  Note that this will fit into a 32-bit variable if
536  * it's a time difference of less than ~4 seconds.
537  *
538  * Example:
539  *      ...
540  *      printf("Forking time is %u nsec\n",
541  *             (unsigned)time_to_nsec(forking_time()));
542  *
543  */
544 static inline uint64_t time_to_nsec(struct timerel t)
545 {
546         uint64_t nsec;
547
548         nsec = TIMEREL_CHECK(t).ts.tv_nsec + (uint64_t)t.ts.tv_sec * 1000000000;
549         return nsec;
550 }
551
552 /**
553  * time_from_sec - convert seconds to a relative time
554  * @msec: time in seconds
555  *
556  * Example:
557  *      // 1 minute timeout
558  *      #define TIMEOUT time_from_sec(60)
559  */
560 static inline struct timerel time_from_sec(uint64_t sec)
561 {
562         struct timerel t;
563
564         t.ts.tv_nsec = 0;
565         t.ts.tv_sec = sec;
566         return TIMEREL_CHECK(t);
567 }
568
569 /**
570  * time_from_msec - convert milliseconds to a relative time
571  * @msec: time in milliseconds
572  *
573  * Example:
574  *      // 1/2 second timeout
575  *      #define TIMEOUT time_from_msec(500)
576  */
577 static inline struct timerel time_from_msec(uint64_t msec)
578 {
579         struct timerel t;
580
581         t.ts.tv_nsec = (msec % 1000) * 1000000;
582         t.ts.tv_sec = msec / 1000;
583         return TIMEREL_CHECK(t);
584 }
585
586 /**
587  * time_from_usec - convert microseconds to a relative time
588  * @usec: time in microseconds
589  *
590  * Example:
591  *      // 1/2 second timeout
592  *      #define TIMEOUT time_from_usec(500000)
593  */
594 static inline struct timerel time_from_usec(uint64_t usec)
595 {
596         struct timerel t;
597
598         t.ts.tv_nsec = (usec % 1000000) * 1000;
599         t.ts.tv_sec = usec / 1000000;
600         return TIMEREL_CHECK(t);
601 }
602
603 /**
604  * time_from_nsec - convert nanoseconds to a relative time
605  * @nsec: time in nanoseconds
606  *
607  * Example:
608  *      // 1/2 second timeout
609  *      #define TIMEOUT time_from_nsec(500000000)
610  */
611 static inline struct timerel time_from_nsec(uint64_t nsec)
612 {
613         struct timerel t;
614
615         t.ts.tv_nsec = nsec % 1000000000;
616         t.ts.tv_sec = nsec / 1000000000;
617         return TIMEREL_CHECK(t);
618 }
619
620 static inline struct timeval timespec_to_timeval(struct timespec ts)
621 {
622         struct timeval tv;
623         tv.tv_sec = ts.tv_sec;
624         tv.tv_usec = ts.tv_nsec / 1000;
625         return tv;
626 }
627
628 /**
629  * timerel_to_timeval - convert a relative time to a timeval.
630  * @t: a relative time.
631  *
632  * Example:
633  *      struct timerel t = { { 100, 0 } }; // 100 seconds
634  *      struct timeval tv;
635  *
636  *      tv = timerel_to_timeval(t);
637  *      printf("time = %lu.%06u\n", (long)tv.tv_sec, (int)tv.tv_usec);
638  */
639 static inline struct timeval timerel_to_timeval(struct timerel t)
640 {
641         return timespec_to_timeval(t.ts);
642 }
643
644 /**
645  * timeabs_to_timeval - convert an absolute time to a timeval.
646  * @t: an absolute time.
647  *
648  * Example:
649  *      struct timeval tv;
650  *
651  *      tv = timeabs_to_timeval(time_now());
652  *      printf("time = %lu.%06u\n", (long)tv.tv_sec, (int)tv.tv_usec);
653  */
654 static inline struct timeval timeabs_to_timeval(struct timeabs t)
655 {
656         return timespec_to_timeval(t.ts);
657 }
658
659 static inline struct timespec timeval_to_timespec(struct timeval tv)
660 {
661         struct timespec ts;
662         ts.tv_sec = tv.tv_sec;
663         ts.tv_nsec = tv.tv_usec * 1000;
664         return ts;
665 }
666
667 /**
668  * timeval_to_timerel - convert a timeval to a relative time.
669  * @tv: a timeval.
670  *
671  * Example:
672  *      struct timeval tv = { 0, 500 };
673  *      struct timerel t;
674  *
675  *      t = timeval_to_timerel(tv);
676  *      printf("timerel = %lu.%09lu\n", (long)t.ts.tv_sec, (long)t.ts.tv_nsec);
677  */
678 static inline struct timerel timeval_to_timerel(struct timeval tv)
679 {
680         struct timerel t;
681         t.ts = timeval_to_timespec(tv);
682         return TIMEREL_CHECK(t);
683 }
684
685 /**
686  * timeval_to_timeabs - convert a timeval to an absolute time.
687  * @tv: a timeval.
688  *
689  * Example:
690  *      struct timeval tv = { 1401762008, 500 };
691  *      struct timeabs t;
692  *
693  *      t = timeval_to_timeabs(tv);
694  *      printf("timeabs = %lu.%09lu\n", (long)t.ts.tv_sec, (long)t.ts.tv_nsec);
695  */
696 static inline struct timeabs timeval_to_timeabs(struct timeval tv)
697 {
698         struct timeabs t;
699         t.ts = timeval_to_timespec(tv);
700         return TIMEABS_CHECK(t);
701 }
702 #endif /* CCAN_TIME_H */