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