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