src/include/gnunet_time_lib.h

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