git.ozlabs.org Git - ccan/blob - 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  * timerel_add - add two relative times
 393  * @a: one relative time.
 394  * @b: another relative time.
 395  *
 396  * The times must not overflow, or the results are undefined.
 397  *
 398  * Example:
 399  *      static struct timerel double_time(struct timerel a)
 400  *      {
 401  *              return timerel_add(a, a);
 402  *      }
 403  */
 404 static inline struct timerel timerel_add(struct timerel a, struct timerel b)
 405 {
 406         struct timerel t;
 407
 408         t.ts = time_add_(a.ts, b.ts);
 409         return t;
 410 }
 411
 412 /**
 413  * time_divide - divide a time by a value.
 414  * @t: a time.
 415  * @div: number to divide it by.
 416  *
 417  * Example:
 418  *      // How long does it take to do a fork?
 419  *      static struct timerel forking_time(void)
 420  *      {
 421  *              struct timeabs start = time_now();
 422  *              unsigned int i;
 423  *
 424  *              for (i = 0; i < 1000; i++) {
 425  *                      if (fork() != 0) {
 426  *                              exit(0);
 427  *                      }
 428  *                      wait(NULL);
 429  *              }
 430  *              return time_divide(time_between(time_now(), start), i);
 431  *      }
 432  */
 433 struct timerel time_divide(struct timerel t, unsigned long div);
 434
 435 /**
 436  * time_multiply - multiply a time by a value.
 437  * @t: a relative time.
 438  * @mult: number to multiply it by.
 439  *
 440  * Example:
 441  *      ...
 442  *      printf("Time to do 100000 forks would be %u sec\n",
 443  *             (unsigned)time_multiply(forking_time(), 1000000).ts.tv_sec);
 444  */
 445 struct timerel time_multiply(struct timerel t, unsigned long mult);
 446
 447 /**
 448  * time_to_sec - return number of seconds
 449  * @t: a time
 450  *
 451  * It's often more convenient to deal with time values as seconds.
 452  * Note that this will fit into an unsigned 32-bit variable if it's a
 453  * time of less than about 136 years.
 454  *
 455  * Example:
 456  *      ...
 457  *      printf("Forking time is %u sec\n",
 458  *             (unsigned)time_to_sec(forking_time()));
 459  */
 460 static inline uint64_t time_to_sec(struct timerel t)
 461 {
 462         return t.ts.tv_sec;
 463 }
 464
 465 /**
 466  * time_to_msec - return number of milliseconds
 467  * @t: a relative time
 468  *
 469  * It's often more convenient to deal with time values as
 470  * milliseconds.  Note that this will fit into a 32-bit variable if
 471  * it's a time difference of less than ~7 weeks.
 472  *
 473  * Example:
 474  *      ...
 475  *      printf("Forking time is %u msec\n",
 476  *             (unsigned)time_to_msec(forking_time()));
 477  */
 478 static inline uint64_t time_to_msec(struct timerel t)
 479 {
 480         uint64_t msec;
 481
 482         msec = TIMEREL_CHECK(t).ts.tv_nsec/1000000 + (uint64_t)t.ts.tv_sec*1000;
 483         return msec;
 484 }
 485
 486 /**
 487  * time_to_usec - return number of microseconds
 488  * @t: a relative time
 489  *
 490  * It's often more convenient to deal with time values as
 491  * microseconds.  Note that this will fit into a 32-bit variable if
 492  * it's a time difference of less than ~1 hour.
 493  *
 494  * Example:
 495  *      ...
 496  *      printf("Forking time is %u usec\n",
 497  *             (unsigned)time_to_usec(forking_time()));
 498  *
 499  */
 500 static inline uint64_t time_to_usec(struct timerel t)
 501 {
 502         uint64_t usec;
 503
 504         usec = TIMEREL_CHECK(t).ts.tv_nsec/1000 + (uint64_t)t.ts.tv_sec*1000000;
 505         return usec;
 506 }
 507
 508 /**
 509  * time_to_nsec - return number of nanoseconds
 510  * @t: a relative time
 511  *
 512  * It's sometimes more convenient to deal with time values as
 513  * nanoseconds.  Note that this will fit into a 32-bit variable if
 514  * it's a time difference of less than ~4 seconds.
 515  *
 516  * Example:
 517  *      ...
 518  *      printf("Forking time is %u nsec\n",
 519  *             (unsigned)time_to_nsec(forking_time()));
 520  *
 521  */
 522 static inline uint64_t time_to_nsec(struct timerel t)
 523 {
 524         uint64_t nsec;
 525
 526         nsec = TIMEREL_CHECK(t).ts.tv_nsec + (uint64_t)t.ts.tv_sec * 1000000000;
 527         return nsec;
 528 }
 529
 530 /**
 531  * time_from_sec - convert seconds to a relative time
 532  * @msec: time in seconds
 533  *
 534  * Example:
 535  *      // 1 minute timeout
 536  *      #define TIMEOUT time_from_sec(60)
 537  */
 538 static inline struct timerel time_from_sec(uint64_t sec)
 539 {
 540         struct timerel t;
 541
 542         t.ts.tv_nsec = 0;
 543         t.ts.tv_sec = sec;
 544         return TIMEREL_CHECK(t);
 545 }
 546
 547 /**
 548  * time_from_msec - convert milliseconds to a relative time
 549  * @msec: time in milliseconds
 550  *
 551  * Example:
 552  *      // 1/2 second timeout
 553  *      #define TIMEOUT time_from_msec(500)
 554  */
 555 static inline struct timerel time_from_msec(uint64_t msec)
 556 {
 557         struct timerel t;
 558
 559         t.ts.tv_nsec = (msec % 1000) * 1000000;
 560         t.ts.tv_sec = msec / 1000;
 561         return TIMEREL_CHECK(t);
 562 }
 563
 564 /**
 565  * time_from_usec - convert microseconds to a relative time
 566  * @usec: time in microseconds
 567  *
 568  * Example:
 569  *      // 1/2 second timeout
 570  *      #define TIMEOUT time_from_usec(500000)
 571  */
 572 static inline struct timerel time_from_usec(uint64_t usec)
 573 {
 574         struct timerel t;
 575
 576         t.ts.tv_nsec = (usec % 1000000) * 1000;
 577         t.ts.tv_sec = usec / 1000000;
 578         return TIMEREL_CHECK(t);
 579 }
 580
 581 /**
 582  * time_from_nsec - convert nanoseconds to a relative time
 583  * @nsec: time in nanoseconds
 584  *
 585  * Example:
 586  *      // 1/2 second timeout
 587  *      #define TIMEOUT time_from_nsec(500000000)
 588  */
 589 static inline struct timerel time_from_nsec(uint64_t nsec)
 590 {
 591         struct timerel t;
 592
 593         t.ts.tv_nsec = nsec % 1000000000;
 594         t.ts.tv_sec = nsec / 1000000000;
 595         return TIMEREL_CHECK(t);
 596 }
 597
 598 static inline struct timeval timespec_to_timeval(struct timespec ts)
 599 {
 600         struct timeval tv;
 601         tv.tv_sec = ts.tv_sec;
 602         tv.tv_usec = ts.tv_nsec / 1000;
 603         return tv;
 604 }
 605
 606 /**
 607  * timerel_to_timeval - convert a relative time to a timeval.
 608  * @t: a relative time.
 609  *
 610  * Example:
 611  *      struct timerel t = { { 100, 0 } }; // 100 seconds
 612  *      struct timeval tv;
 613  *
 614  *      tv = timerel_to_timeval(t);
 615  *      printf("time = %lu.%06u\n", (long)tv.tv_sec, (int)tv.tv_usec);
 616  */
 617 static inline struct timeval timerel_to_timeval(struct timerel t)
 618 {
 619         return timespec_to_timeval(t.ts);
 620 }
 621
 622 /**
 623  * timeabs_to_timeval - convert an absolute time to a timeval.
 624  * @t: an absolute time.
 625  *
 626  * Example:
 627  *      struct timeval tv;
 628  *
 629  *      tv = timeabs_to_timeval(time_now());
 630  *      printf("time = %lu.%06u\n", (long)tv.tv_sec, (int)tv.tv_usec);
 631  */
 632 static inline struct timeval timeabs_to_timeval(struct timeabs t)
 633 {
 634         return timespec_to_timeval(t.ts);
 635 }
 636
 637 static inline struct timespec timeval_to_timespec(struct timeval tv)
 638 {
 639         struct timespec ts;
 640         ts.tv_sec = tv.tv_sec;
 641         ts.tv_nsec = tv.tv_usec * 1000;
 642         return ts;
 643 }
 644
 645 /**
 646  * timeval_to_timerel - convert a timeval to a relative time.
 647  * @tv: a timeval.
 648  *
 649  * Example:
 650  *      struct timeval tv = { 0, 500 };
 651  *      struct timerel t;
 652  *
 653  *      t = timeval_to_timerel(tv);
 654  *      printf("timerel = %lu.%09lu\n", (long)t.ts.tv_sec, (long)t.ts.tv_nsec);
 655  */
 656 static inline struct timerel timeval_to_timerel(struct timeval tv)
 657 {
 658         struct timerel t;
 659         t.ts = timeval_to_timespec(tv);
 660         return TIMEREL_CHECK(t);
 661 }
 662
 663 /**
 664  * timeval_to_timeabs - convert a timeval to an absolute time.
 665  * @tv: a timeval.
 666  *
 667  * Example:
 668  *      struct timeval tv = { 1401762008, 500 };
 669  *      struct timeabs t;
 670  *
 671  *      t = timeval_to_timeabs(tv);
 672  *      printf("timeabs = %lu.%09lu\n", (long)t.ts.tv_sec, (long)t.ts.tv_nsec);
 673  */
 674 static inline struct timeabs timeval_to_timeabs(struct timeval tv)
 675 {
 676         struct timeabs t;
 677         t.ts = timeval_to_timespec(tv);
 678         return TIMEABS_CHECK(t);
 679 }
 680 #endif /* CCAN_TIME_H */