src/include/gnunet_time_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2013 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Functions related to time
  26  *
  27  * @defgroup time  Time library
  28  * Time and time calculations.
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_TIME_LIB_H
  33 #define GNUNET_TIME_LIB_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_common.h"
  44
  45 /**
  46  * Time for absolute times used by GNUnet, in microseconds.
  47  */
  48 struct GNUNET_TIME_Absolute
  49 {
  50   /**
  51    * The actual value.
  52    */
  53   uint64_t abs_value_us;
  54 };
  55
  56 /**
  57  * Time for relative time used by GNUnet, in microseconds.
  58  * Always positive, so we can only refer to future time.
  59  */
  60 struct GNUNET_TIME_Relative
  61 {
  62   /**
  63    * The actual value.
  64    */
  65   uint64_t rel_value_us;
  66 };
  67
  68 GNUNET_NETWORK_STRUCT_BEGIN
  69
  70 /**
  71  * Time for relative time used by GNUnet, in microseconds and in network byte order.
  72  */
  73 struct GNUNET_TIME_RelativeNBO
  74 {
  75   /**
  76    * The actual value (in network byte order).
  77    */
  78   uint64_t rel_value_us__ GNUNET_PACKED;
  79 };
  80
  81
  82 /**
  83  * Time for absolute time used by GNUnet, in microseconds and in network byte order.
  84  */
  85 struct GNUNET_TIME_AbsoluteNBO
  86 {
  87   /**
  88    * The actual value (in network byte order).
  89    */
  90   uint64_t abs_value_us__ GNUNET_PACKED;
  91 };
  92 GNUNET_NETWORK_STRUCT_END
  93
  94 /**
  95  * Relative time zero.
  96  */
  97 #define GNUNET_TIME_UNIT_ZERO     GNUNET_TIME_relative_get_zero_ ()
  98
  99 /**
 100  * Absolute time zero.
 101  */
 102 #define GNUNET_TIME_UNIT_ZERO_ABS GNUNET_TIME_absolute_get_zero_ ()
 103
 104 /**
 105  * One microsecond, our basic time unit.
 106  */
 107 #define GNUNET_TIME_UNIT_MICROSECONDS GNUNET_TIME_relative_get_unit_ ()
 108
 109 /**
 110  * One millisecond.
 111  */
 112 #define GNUNET_TIME_UNIT_MILLISECONDS GNUNET_TIME_relative_get_millisecond_ ()
 113
 114 /**
 115  * One second.
 116  */
 117 #define GNUNET_TIME_UNIT_SECONDS GNUNET_TIME_relative_get_second_ ()
 118
 119 /**
 120  * One minute.
 121  */
 122 #define GNUNET_TIME_UNIT_MINUTES GNUNET_TIME_relative_get_minute_ ()
 123
 124 /**
 125  * One hour.
 126  */
 127 #define GNUNET_TIME_UNIT_HOURS   GNUNET_TIME_relative_get_hour_ ()
 128
 129 /**
 130  * One day.
 131  */
 132 #define GNUNET_TIME_UNIT_DAYS    GNUNET_TIME_relative_multiply ( \
 133     GNUNET_TIME_UNIT_HOURS, 24)
 134
 135 /**
 136  * One week.
 137  */
 138 #define GNUNET_TIME_UNIT_WEEKS   GNUNET_TIME_relative_multiply ( \
 139     GNUNET_TIME_UNIT_DAYS, 7)
 140
 141 /**
 142  * One month (30 days).
 143  */
 144 #define GNUNET_TIME_UNIT_MONTHS  GNUNET_TIME_relative_multiply ( \
 145     GNUNET_TIME_UNIT_DAYS, 30)
 146
 147 /**
 148  * One year (365 days).
 149  */
 150 #define GNUNET_TIME_UNIT_YEARS   GNUNET_TIME_relative_multiply ( \
 151     GNUNET_TIME_UNIT_DAYS, 365)
 152
 153 /**
 154  * Constant used to specify "forever".  This constant
 155  * will be treated specially in all time operations.
 156  */
 157 #define GNUNET_TIME_UNIT_FOREVER_REL GNUNET_TIME_relative_get_forever_ ()
 158
 159 /**
 160  * Constant used to specify "forever".  This constant
 161  * will be treated specially in all time operations.
 162  */
 163 #define GNUNET_TIME_UNIT_FOREVER_ABS GNUNET_TIME_absolute_get_forever_ ()
 164
 165
 166 /**
 167  * Threshold after which exponential backoff should not increase (15 m).
 168  */
 169 #define GNUNET_TIME_STD_EXPONENTIAL_BACKOFF_THRESHOLD \
 170   GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MINUTES, 15)
 171
 172
 173 /**
 174  * Perform our standard exponential back-off calculation, starting at 1 ms
 175  * and then going by a factor of 2 up unto a maximum of 15 m.
 176  *
 177  * @param r current backoff time, initially zero
 178  */
 179 #define GNUNET_TIME_STD_BACKOFF(r) GNUNET_TIME_relative_min ( \
 180     GNUNET_TIME_STD_EXPONENTIAL_BACKOFF_THRESHOLD, \
 181     GNUNET_TIME_relative_multiply ( \
 182       GNUNET_TIME_relative_max (GNUNET_TIME_UNIT_MILLISECONDS, (r)), 2));
 183
 184
 185 /**
 186  * Randomized exponential back-off, starting at 1 ms
 187  * and going up by a factor of 2+r, where 0 <= r <= 0.5, up
 188  * to a maximum of the given threshold.
 189  *
 190  * @param rt current backoff time, initially zero
 191  * @param threshold maximum value for backoff
 192  * @return the next backoff time
 193  */
 194 struct GNUNET_TIME_Relative
 195 GNUNET_TIME_randomized_backoff (struct GNUNET_TIME_Relative rt, struct
 196                                 GNUNET_TIME_Relative threshold);
 197
 198
 199 /**
 200  * Return a random time value between 0.5*r and 1.5*r.
 201  *
 202  * @param r input time for scaling
 203  * @return randomized time
 204  */
 205 struct GNUNET_TIME_Relative
 206 GNUNET_TIME_randomize (struct GNUNET_TIME_Relative r);
 207
 208
 209 /**
 210  * Return relative time of 0ms.
 211  */
 212 struct GNUNET_TIME_Relative
 213 GNUNET_TIME_relative_get_zero_ (void);
 214
 215
 216 /**
 217  * Return absolute time of 0ms.
 218  */
 219 struct GNUNET_TIME_Absolute
 220 GNUNET_TIME_absolute_get_zero_ (void);
 221
 222
 223 /**
 224  * Return relative time of 1 microsecond.
 225  */
 226 struct GNUNET_TIME_Relative
 227 GNUNET_TIME_relative_get_unit_ (void);
 228
 229
 230 /**
 231  * Return relative time of 1ms.
 232  */
 233 struct GNUNET_TIME_Relative
 234 GNUNET_TIME_relative_get_millisecond_ (void);
 235
 236
 237 /**
 238  * Return relative time of 1s.
 239  */
 240 struct GNUNET_TIME_Relative
 241 GNUNET_TIME_relative_get_second_ (void);
 242
 243
 244 /**
 245  * Return relative time of 1 minute.
 246  */
 247 struct GNUNET_TIME_Relative
 248 GNUNET_TIME_relative_get_minute_ (void);
 249
 250
 251 /**
 252  * Return relative time of 1 hour.
 253  */
 254 struct GNUNET_TIME_Relative
 255 GNUNET_TIME_relative_get_hour_ (void);
 256
 257
 258 /**
 259  * Return "forever".
 260  */
 261 struct GNUNET_TIME_Relative
 262 GNUNET_TIME_relative_get_forever_ (void);
 263
 264
 265 /**
 266  * Return "forever".
 267  */
 268 struct GNUNET_TIME_Absolute
 269 GNUNET_TIME_absolute_get_forever_ (void);
 270
 271
 272 /**
 273  * Get the current time.
 274  *
 275  * @return the current time
 276  */
 277 struct GNUNET_TIME_Absolute
 278 GNUNET_TIME_absolute_get (void);
 279
 280
 281 /**
 282  * Convert relative time to an absolute time in the
 283  * future.
 284  *
 285  * @param rel relative time to convert
 286  * @return timestamp that is "rel" in the future, or FOREVER if rel==FOREVER (or if we would overflow)
 287  */
 288 struct GNUNET_TIME_Absolute
 289 GNUNET_TIME_relative_to_absolute (struct GNUNET_TIME_Relative rel);
 290
 291
 292 /**
 293  * Round a time value so that it is suitable for transmission
 294  * via JSON encodings.
 295  *
 296  * @param at time to round
 297  * @return #GNUNET_OK if time was already rounded, #GNUNET_NO if
 298  *         it was just now rounded
 299  */
 300 int
 301 GNUNET_TIME_round_abs (struct GNUNET_TIME_Absolute *at);
 302
 303
 304 /**
 305  * Round a time value so that it is suitable for transmission
 306  * via JSON encodings.
 307  *
 308  * @param rt time to round
 309  * @return #GNUNET_OK if time was already rounded, #GNUNET_NO if
 310  *         it was just now rounded
 311  */
 312 int
 313 GNUNET_TIME_round_rel (struct GNUNET_TIME_Relative *rt);
 314
 315
 316 /**
 317  * Return the minimum of two relative time values.
 318  *
 319  * @param t1 first timestamp
 320  * @param t2 other timestamp
 321  * @return timestamp that is smaller
 322  */
 323 struct GNUNET_TIME_Relative
 324 GNUNET_TIME_relative_min (struct GNUNET_TIME_Relative t1,
 325                           struct GNUNET_TIME_Relative t2);
 326
 327
 328 /**
 329  * Return the maximum of two relative time values.
 330  *
 331  * @param t1 first timestamp
 332  * @param t2 other timestamp
 333  * @return timestamp that is larger
 334  */
 335 struct GNUNET_TIME_Relative
 336 GNUNET_TIME_relative_max (struct GNUNET_TIME_Relative t1,
 337                           struct GNUNET_TIME_Relative t2);
 338
 339
 340 /**
 341  * Return the minimum of two absolute time values.
 342  *
 343  * @param t1 first timestamp
 344  * @param t2 other timestamp
 345  * @return timestamp that is smaller
 346  */
 347 struct GNUNET_TIME_Absolute
 348 GNUNET_TIME_absolute_min (struct GNUNET_TIME_Absolute t1,
 349                           struct GNUNET_TIME_Absolute t2);
 350
 351
 352 /**
 353  * Return the maximum of two absolute time values.
 354  *
 355  * @param t1 first timestamp
 356  * @param t2 other timestamp
 357  * @return timestamp that is smaller
 358  */
 359 struct GNUNET_TIME_Absolute
 360 GNUNET_TIME_absolute_max (struct GNUNET_TIME_Absolute t1,
 361                           struct GNUNET_TIME_Absolute t2);
 362
 363
 364 /**
 365  * Given a timestamp in the future, how much time
 366  * remains until then?
 367  *
 368  * @param future some absolute time, typically in the future
 369  * @return future - now, or 0 if now >= future, or FOREVER if future==FOREVER.
 370  */
 371 struct GNUNET_TIME_Relative
 372 GNUNET_TIME_absolute_get_remaining (struct GNUNET_TIME_Absolute future);
 373
 374
 375 /**
 376  * Calculate the estimate time of arrival/completion
 377  * for an operation.
 378  *
 379  * @param start when did the operation start?
 380  * @param finished how much has been done?
 381  * @param total how much must be done overall (same unit as for "finished")
 382  * @return remaining duration for the operation,
 383  *        assuming it continues at the same speed
 384  */
 385 struct GNUNET_TIME_Relative
 386 GNUNET_TIME_calculate_eta (struct GNUNET_TIME_Absolute start,
 387                            uint64_t finished,
 388                            uint64_t total);
 389
 390
 391 /**
 392  * Compute the time difference between the given start and end times.
 393  * Use this function instead of actual subtraction to ensure that
 394  * "FOREVER" and overflows are handeled correctly.
 395  *
 396  * @param start some absolute time
 397  * @param end some absolute time (typically larger or equal to start)
 398  * @return 0 if start >= end; FOREVER if end==FOREVER; otherwise end - start
 399  */
 400 struct GNUNET_TIME_Relative
 401 GNUNET_TIME_absolute_get_difference (struct GNUNET_TIME_Absolute start,
 402                                      struct GNUNET_TIME_Absolute end);
 403
 404
 405 /**
 406  * Get the duration of an operation as the
 407  * difference of the current time and the given start time "hence".
 408  *
 409  * @param whence some absolute time, typically in the past
 410  * @return 0 if hence > now, otherwise now-hence.
 411  */
 412 struct GNUNET_TIME_Relative
 413 GNUNET_TIME_absolute_get_duration (struct GNUNET_TIME_Absolute whence);
 414
 415
 416 /**
 417  * Add a given relative duration to the
 418  * given start time.
 419  *
 420  * @param start some absolute time
 421  * @param duration some relative time to add
 422  * @return FOREVER if either argument is FOREVER or on overflow; start+duration otherwise
 423  */
 424 struct GNUNET_TIME_Absolute
 425 GNUNET_TIME_absolute_add (struct GNUNET_TIME_Absolute start,
 426                           struct GNUNET_TIME_Relative duration);
 427
 428
 429 /**
 430  * Subtract a given relative duration from the
 431  * given start time.
 432  *
 433  * @param start some absolute time
 434  * @param duration some relative time to subtract
 435  * @return ZERO if start <= duration, or FOREVER if start time is FOREVER; start-duration otherwise
 436  */
 437 struct GNUNET_TIME_Absolute
 438 GNUNET_TIME_absolute_subtract (struct GNUNET_TIME_Absolute start,
 439                                struct GNUNET_TIME_Relative duration);
 440
 441
 442 /**
 443  * Multiply relative time by a given factor.
 444  *
 445  * @param rel some duration
 446  * @param factor integer to multiply with
 447  * @return FOREVER if rel=FOREVER or on overflow; otherwise rel*factor
 448  */
 449 struct GNUNET_TIME_Relative
 450 GNUNET_TIME_relative_multiply (struct GNUNET_TIME_Relative rel,
 451                                unsigned long long factor);
 452
 453
 454 /**
 455  * Saturating multiply relative time by a given factor.
 456  *
 457  * @param rel some duration
 458  * @param factor integer to multiply with
 459  * @return FOREVER if rel=FOREVER or on overflow; otherwise rel*factor
 460  */
 461 struct GNUNET_TIME_Relative
 462 GNUNET_TIME_relative_saturating_multiply (struct GNUNET_TIME_Relative rel,
 463                                           unsigned long long factor);
 464
 465
 466 /**
 467  * Divide relative time by a given factor.
 468  *
 469  * @param rel some duration
 470  * @param factor integer to divide by
 471  * @return FOREVER if rel=FOREVER or factor==0; otherwise rel/factor
 472  */
 473 struct GNUNET_TIME_Relative
 474 GNUNET_TIME_relative_divide (struct GNUNET_TIME_Relative rel,
 475                              unsigned long long factor);
 476
 477
 478 /**
 479  * Add relative times together.
 480  *
 481  * @param a1 some relative time
 482  * @param a2 some other relative time
 483  * @return FOREVER if either argument is FOREVER or on overflow; a1+a2 otherwise
 484  */
 485 struct GNUNET_TIME_Relative
 486 GNUNET_TIME_relative_add (struct GNUNET_TIME_Relative a1,
 487                           struct GNUNET_TIME_Relative a2);
 488
 489
 490 /**
 491  * Subtract relative timestamp from the other.
 492  *
 493  * @param a1 first timestamp
 494  * @param a2 second timestamp
 495  * @return ZERO if a2>=a1 (including both FOREVER), FOREVER if a1 is FOREVER, a1-a2 otherwise
 496  */
 497 struct GNUNET_TIME_Relative
 498 GNUNET_TIME_relative_subtract (struct GNUNET_TIME_Relative a1,
 499                                struct GNUNET_TIME_Relative a2);
 500
 501
 502 /**
 503  * Convert relative time to network byte order.
 504  *
 505  * @param a time to convert
 506  * @return converted time value
 507  */
 508 struct GNUNET_TIME_RelativeNBO
 509 GNUNET_TIME_relative_hton (struct GNUNET_TIME_Relative a);
 510
 511
 512 /**
 513  * Convert relative time from network byte order.
 514  *
 515  * @param a time to convert
 516  * @return converted time value
 517  */
 518 struct GNUNET_TIME_Relative
 519 GNUNET_TIME_relative_ntoh (struct GNUNET_TIME_RelativeNBO a);
 520
 521
 522 /**
 523  * Convert absolute time to network byte order.
 524  *
 525  * @param a time to convert
 526  * @return converted time value
 527  */
 528 struct GNUNET_TIME_AbsoluteNBO
 529 GNUNET_TIME_absolute_hton (struct GNUNET_TIME_Absolute a);
 530
 531
 532 /**
 533  * Convert absolute time from network byte order.
 534  *
 535  * @param a time to convert
 536  * @return converted time value
 537  */
 538 struct GNUNET_TIME_Absolute
 539 GNUNET_TIME_absolute_ntoh (struct GNUNET_TIME_AbsoluteNBO a);
 540
 541
 542 /**
 543  * Set the timestamp offset for this instance.
 544  *
 545  * @param offset the offset to skew the locale time by
 546  */
 547 void
 548 GNUNET_TIME_set_offset (long long offset);
 549
 550
 551 /**
 552  * Get the timestamp offset for this instance.
 553  *
 554  * @return the offset we currently skew the locale time by
 555  */
 556 long long
 557 GNUNET_TIME_get_offset (void);
 558
 559
 560 /**
 561  * Return the current year (i.e. '2011').
 562  */
 563 unsigned int
 564 GNUNET_TIME_get_current_year (void);
 565
 566
 567 /**
 568  * Convert a year to an expiration time of January 1st of that year.
 569  *
 570  * @param year a year (after 1970, please ;-)).
 571  * @return absolute time for January 1st of that year.
 572  */
 573 struct GNUNET_TIME_Absolute
 574 GNUNET_TIME_year_to_time (unsigned int year);
 575
 576
 577 /**
 578  * Convert an expiration time to the respective year (rounds)
 579  *
 580  * @param at absolute time
 581  * @return year a year (after 1970), 0 on error
 582  */
 583 unsigned int
 584 GNUNET_TIME_time_to_year (struct GNUNET_TIME_Absolute at);
 585
 586
 587 /**
 588  * A configuration object.
 589  */
 590 struct GNUNET_CONFIGURATION_Handle;
 591
 592
 593 /**
 594  * Obtain the current time and make sure it is monotonically
 595  * increasing.  Guards against systems without an RTC or
 596  * clocks running backwards and other nasty surprises. Does
 597  * not guarantee that the returned time is near the current
 598  * time returned by #GNUNET_TIME_absolute_get().  Two
 599  * subsequent calls (within a short time period) may return the
 600  * same value. Persists the last returned time on disk to
 601  * ensure that time never goes backwards. As a result, the
 602  * resulting value can be used to check if a message is the
 603  * "most recent" value and replays of older messages (from
 604  * the same origin) would be discarded.
 605  *
 606  * @param cfg configuration, used to determine where to
 607  *   store the time; user can also insist RTC is working
 608  *   nicely and disable the feature
 609  * @return monotonically increasing time
 610  */
 611 struct GNUNET_TIME_Absolute
 612 GNUNET_TIME_absolute_get_monotonic (const struct
 613                                     GNUNET_CONFIGURATION_Handle *cfg);
 614
 615
 616 #if 0                           /* keep Emacsens' auto-indent happy */
 617 {
 618 #endif
 619 #ifdef __cplusplus
 620 }
 621 #endif
 622
 623 /* ifndef GNUNET_TIME_LIB_H */
 624 #endif
 625
 626 /** @} */ /* end of group time */
 627
 628 /* end of gnunet_time_lib.h */