src/libstd/time.rs

   1 //! Temporal quantification.
   2 //!
   3 //! Example:
   4 //!
   5 //! ```
   6 //! use std::time::Duration;
   7 //!
   8 //! let five_seconds = Duration::new(5, 0);
   9 //! // both declarations are equivalent
  10 //! assert_eq!(Duration::new(5, 0), Duration::from_secs(5));
  11 //! ```
  12
  13 #![stable(feature = "time", since = "1.3.0")]
  14
  15 use crate::cmp;
  16 use crate::error::Error;
  17 use crate::fmt;
  18 use crate::ops::{Add, Sub, AddAssign, SubAssign};
  19 use crate::sys::time;
  20 use crate::sys_common::FromInner;
  21 use crate::sys_common::mutex::Mutex;
  22
  23 #[stable(feature = "time", since = "1.3.0")]
  24 pub use core::time::Duration;
  25
  26 /// A measurement of a monotonically nondecreasing clock.
  27 /// Opaque and useful only with `Duration`.
  28 ///
  29 /// Instants are always guaranteed to be no less than any previously measured
  30 /// instant when created, and are often useful for tasks such as measuring
  31 /// benchmarks or timing how long an operation takes.
  32 ///
  33 /// Note, however, that instants are not guaranteed to be **steady**. In other
  34 /// words, each tick of the underlying clock may not be the same length (e.g.
  35 /// some seconds may be longer than others). An instant may jump forwards or
  36 /// experience time dilation (slow down or speed up), but it will never go
  37 /// backwards.
  38 ///
  39 /// Instants are opaque types that can only be compared to one another. There is
  40 /// no method to get "the number of seconds" from an instant. Instead, it only
  41 /// allows measuring the duration between two instants (or comparing two
  42 /// instants).
  43 ///
  44 /// The size of an `Instant` struct may vary depending on the target operating
  45 /// system.
  46 ///
  47 /// Example:
  48 ///
  49 /// ```no_run
  50 /// use std::time::{Duration, Instant};
  51 /// use std::thread::sleep;
  52 ///
  53 /// fn main() {
  54 ///    let now = Instant::now();
  55 ///
  56 ///    // we sleep for 2 seconds
  57 ///    sleep(Duration::new(2, 0));
  58 ///    // it prints '2'
  59 ///    println!("{}", now.elapsed().as_secs());
  60 /// }
  61 /// ```
  62 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
  63 #[stable(feature = "time2", since = "1.8.0")]
  64 pub struct Instant(time::Instant);
  65
  66 /// A measurement of the system clock, useful for talking to
  67 /// external entities like the file system or other processes.
  68 ///
  69 /// Distinct from the [`Instant`] type, this time measurement **is not
  70 /// monotonic**. This means that you can save a file to the file system, then
  71 /// save another file to the file system, **and the second file has a
  72 /// `SystemTime` measurement earlier than the first**. In other words, an
  73 /// operation that happens after another operation in real time may have an
  74 /// earlier `SystemTime`!
  75 ///
  76 /// Consequently, comparing two `SystemTime` instances to learn about the
  77 /// duration between them returns a [`Result`] instead of an infallible [`Duration`]
  78 /// to indicate that this sort of time drift may happen and needs to be handled.
  79 ///
  80 /// Although a `SystemTime` cannot be directly inspected, the [`UNIX_EPOCH`]
  81 /// constant is provided in this module as an anchor in time to learn
  82 /// information about a `SystemTime`. By calculating the duration from this
  83 /// fixed point in time, a `SystemTime` can be converted to a human-readable time,
  84 /// or perhaps some other string representation.
  85 ///
  86 /// The size of a `SystemTime` struct may vary depending on the target operating
  87 /// system.
  88 ///
  89 /// [`Instant`]: ../../std/time/struct.Instant.html
  90 /// [`Result`]: ../../std/result/enum.Result.html
  91 /// [`Duration`]: ../../std/time/struct.Duration.html
  92 /// [`UNIX_EPOCH`]: ../../std/time/constant.UNIX_EPOCH.html
  93 ///
  94 /// Example:
  95 ///
  96 /// ```no_run
  97 /// use std::time::{Duration, SystemTime};
  98 /// use std::thread::sleep;
  99 ///
 100 /// fn main() {
 101 ///    let now = SystemTime::now();
 102 ///
 103 ///    // we sleep for 2 seconds
 104 ///    sleep(Duration::new(2, 0));
 105 ///    match now.elapsed() {
 106 ///        Ok(elapsed) => {
 107 ///            // it prints '2'
 108 ///            println!("{}", elapsed.as_secs());
 109 ///        }
 110 ///        Err(e) => {
 111 ///            // an error occurred!
 112 ///            println!("Error: {:?}", e);
 113 ///        }
 114 ///    }
 115 /// }
 116 /// ```
 117 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 118 #[stable(feature = "time2", since = "1.8.0")]
 119 pub struct SystemTime(time::SystemTime);
 120
 121 /// An error returned from the `duration_since` and `elapsed` methods on
 122 /// `SystemTime`, used to learn how far in the opposite direction a system time
 123 /// lies.
 124 ///
 125 /// # Examples
 126 ///
 127 /// ```no_run
 128 /// use std::thread::sleep;
 129 /// use std::time::{Duration, SystemTime};
 130 ///
 131 /// let sys_time = SystemTime::now();
 132 /// sleep(Duration::from_secs(1));
 133 /// let new_sys_time = SystemTime::now();
 134 /// match sys_time.duration_since(new_sys_time) {
 135 ///     Ok(_) => {}
 136 ///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
 137 /// }
 138 /// ```
 139 #[derive(Clone, Debug)]
 140 #[stable(feature = "time2", since = "1.8.0")]
 141 pub struct SystemTimeError(Duration);
 142
 143 impl Instant {
 144     /// Returns an instant corresponding to "now".
 145     ///
 146     /// # Examples
 147     ///
 148     /// ```
 149     /// use std::time::Instant;
 150     ///
 151     /// let now = Instant::now();
 152     /// ```
 153     #[stable(feature = "time2", since = "1.8.0")]
 154     pub fn now() -> Instant {
 155         let os_now = time::Instant::now();
 156
 157         // And here we come upon a sad state of affairs. The whole point of
 158         // `Instant` is that it's monotonically increasing. We've found in the
 159         // wild, however, that it's not actually monotonically increasing for
 160         // one reason or another. These appear to be OS and hardware level bugs,
 161         // and there's not really a whole lot we can do about them. Here's a
 162         // taste of what we've found:
 163         //
 164         // * #48514 - OpenBSD, x86_64
 165         // * #49281 - linux arm64 and s390x
 166         // * #51648 - windows, x86
 167         // * #56560 - windows, x86_64, AWS
 168         // * #56612 - windows, x86, vm (?)
 169         // * #56940 - linux, arm64
 170         // * https://bugzilla.mozilla.org/show_bug.cgi?id=1487778 - a similar
 171         //   Firefox bug
 172         //
 173         // It simply seems that this it just happens so that a lot in the wild
 174         // we're seeing panics across various platforms where consecutive calls
 175         // to `Instant::now`, such as via the `elapsed` function, are panicking
 176         // as they're going backwards. Placed here is a last-ditch effort to try
 177         // to fix things up. We keep a global "latest now" instance which is
 178         // returned instead of what the OS says if the OS goes backwards.
 179         //
 180         // To hopefully mitigate the impact of this though a few platforms are
 181         // whitelisted as "these at least haven't gone backwards yet".
 182         if time::Instant::actually_monotonic() {
 183             return Instant(os_now)
 184         }
 185
 186         static LOCK: Mutex = Mutex::new();
 187         static mut LAST_NOW: time::Instant = time::Instant::zero();
 188         unsafe {
 189             let _lock = LOCK.lock();
 190             let now = cmp::max(LAST_NOW, os_now);
 191             LAST_NOW = now;
 192             Instant(now)
 193         }
 194     }
 195
 196     /// Returns the amount of time elapsed from another instant to this one.
 197     ///
 198     /// # Panics
 199     ///
 200     /// This function will panic if `earlier` is later than `self`.
 201     ///
 202     /// # Examples
 203     ///
 204     /// ```no_run
 205     /// use std::time::{Duration, Instant};
 206     /// use std::thread::sleep;
 207     ///
 208     /// let now = Instant::now();
 209     /// sleep(Duration::new(1, 0));
 210     /// let new_now = Instant::now();
 211     /// println!("{:?}", new_now.duration_since(now));
 212     /// ```
 213     #[stable(feature = "time2", since = "1.8.0")]
 214     pub fn duration_since(&self, earlier: Instant) -> Duration {
 215         self.0.checked_sub_instant(&earlier.0).expect("supplied instant is later than self")
 216     }
 217
 218     /// Returns the amount of time elapsed from another instant to this one,
 219     /// or None if that instant is earlier than this one.
 220     ///
 221     /// # Examples
 222     ///
 223     /// ```no_run
 224     /// #![feature(checked_duration_since)]
 225     /// use std::time::{Duration, Instant};
 226     /// use std::thread::sleep;
 227     ///
 228     /// let now = Instant::now();
 229     /// sleep(Duration::new(1, 0));
 230     /// let new_now = Instant::now();
 231     /// println!("{:?}", new_now.checked_duration_since(now));
 232     /// println!("{:?}", now.checked_duration_since(new_now)); // None
 233     /// ```
 234     #[unstable(feature = "checked_duration_since", issue = "58402")]
 235     pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
 236         self.0.checked_sub_instant(&earlier.0)
 237     }
 238
 239     /// Returns the amount of time elapsed from another instant to this one,
 240     /// or zero duration if that instant is earlier than this one.
 241     ///
 242     /// # Examples
 243     ///
 244     /// ```no_run
 245     /// #![feature(checked_duration_since)]
 246     /// use std::time::{Duration, Instant};
 247     /// use std::thread::sleep;
 248     ///
 249     /// let now = Instant::now();
 250     /// sleep(Duration::new(1, 0));
 251     /// let new_now = Instant::now();
 252     /// println!("{:?}", new_now.saturating_duration_since(now));
 253     /// println!("{:?}", now.saturating_duration_since(new_now)); // 0ns
 254     /// ```
 255     #[unstable(feature = "checked_duration_since", issue = "58402")]
 256     pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
 257         self.checked_duration_since(earlier).unwrap_or(Duration::new(0, 0))
 258     }
 259
 260     /// Returns the amount of time elapsed since this instant was created.
 261     ///
 262     /// # Panics
 263     ///
 264     /// This function may panic if the current time is earlier than this
 265     /// instant, which is something that can happen if an `Instant` is
 266     /// produced synthetically.
 267     ///
 268     /// # Examples
 269     ///
 270     /// ```no_run
 271     /// use std::thread::sleep;
 272     /// use std::time::{Duration, Instant};
 273     ///
 274     /// let instant = Instant::now();
 275     /// let three_secs = Duration::from_secs(3);
 276     /// sleep(three_secs);
 277     /// assert!(instant.elapsed() >= three_secs);
 278     /// ```
 279     #[stable(feature = "time2", since = "1.8.0")]
 280     pub fn elapsed(&self) -> Duration {
 281         Instant::now() - *self
 282     }
 283
 284     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
 285     /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
 286     /// otherwise.
 287     #[stable(feature = "time_checked_add", since = "1.34.0")]
 288     pub fn checked_add(&self, duration: Duration) -> Option<Instant> {
 289         self.0.checked_add_duration(&duration).map(Instant)
 290     }
 291
 292     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
 293     /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
 294     /// otherwise.
 295     #[stable(feature = "time_checked_add", since = "1.34.0")]
 296     pub fn checked_sub(&self, duration: Duration) -> Option<Instant> {
 297         self.0.checked_sub_duration(&duration).map(Instant)
 298     }
 299 }
 300
 301 #[stable(feature = "time2", since = "1.8.0")]
 302 impl Add<Duration> for Instant {
 303     type Output = Instant;
 304
 305     /// # Panics
 306     ///
 307     /// This function may panic if the resulting point in time cannot be represented by the
 308     /// underlying data structure. See [`checked_add`] for a version without panic.
 309     ///
 310     /// [`checked_add`]: ../../std/time/struct.Instant.html#method.checked_add
 311     fn add(self, other: Duration) -> Instant {
 312         self.checked_add(other)
 313             .expect("overflow when adding duration to instant")
 314     }
 315 }
 316
 317 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 318 impl AddAssign<Duration> for Instant {
 319     fn add_assign(&mut self, other: Duration) {
 320         *self = *self + other;
 321     }
 322 }
 323
 324 #[stable(feature = "time2", since = "1.8.0")]
 325 impl Sub<Duration> for Instant {
 326     type Output = Instant;
 327
 328     fn sub(self, other: Duration) -> Instant {
 329         self.checked_sub(other)
 330             .expect("overflow when subtracting duration from instant")
 331     }
 332 }
 333
 334 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 335 impl SubAssign<Duration> for Instant {
 336     fn sub_assign(&mut self, other: Duration) {
 337         *self = *self - other;
 338     }
 339 }
 340
 341 #[stable(feature = "time2", since = "1.8.0")]
 342 impl Sub<Instant> for Instant {
 343     type Output = Duration;
 344
 345     fn sub(self, other: Instant) -> Duration {
 346         self.duration_since(other)
 347     }
 348 }
 349
 350 #[stable(feature = "time2", since = "1.8.0")]
 351 impl fmt::Debug for Instant {
 352     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 353         self.0.fmt(f)
 354     }
 355 }
 356
 357 impl SystemTime {
 358     /// An anchor in time which can be used to create new `SystemTime` instances or
 359     /// learn about where in time a `SystemTime` lies.
 360     ///
 361     /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 362     /// respect to the system clock. Using `duration_since` on an existing
 363     /// `SystemTime` instance can tell how far away from this point in time a
 364     /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 365     /// `SystemTime` instance to represent another fixed point in time.
 366     ///
 367     /// # Examples
 368     ///
 369     /// ```no_run
 370     /// use std::time::SystemTime;
 371     ///
 372     /// match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) {
 373     ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
 374     ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
 375     /// }
 376     /// ```
 377     #[stable(feature = "assoc_unix_epoch", since = "1.28.0")]
 378     pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH;
 379
 380     /// Returns the system time corresponding to "now".
 381     ///
 382     /// # Examples
 383     ///
 384     /// ```
 385     /// use std::time::SystemTime;
 386     ///
 387     /// let sys_time = SystemTime::now();
 388     /// ```
 389     #[stable(feature = "time2", since = "1.8.0")]
 390     pub fn now() -> SystemTime {
 391         SystemTime(time::SystemTime::now())
 392     }
 393
 394     /// Returns the amount of time elapsed from an earlier point in time.
 395     ///
 396     /// This function may fail because measurements taken earlier are not
 397     /// guaranteed to always be before later measurements (due to anomalies such
 398     /// as the system clock being adjusted either forwards or backwards).
 399     ///
 400     /// If successful, [`Ok`]`(`[`Duration`]`)` is returned where the duration represents
 401     /// the amount of time elapsed from the specified measurement to this one.
 402     ///
 403     /// Returns an [`Err`] if `earlier` is later than `self`, and the error
 404     /// contains how far from `self` the time is.
 405     ///
 406     /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
 407     /// [`Duration`]: ../../std/time/struct.Duration.html
 408     /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
 409     ///
 410     /// # Examples
 411     ///
 412     /// ```
 413     /// use std::time::SystemTime;
 414     ///
 415     /// let sys_time = SystemTime::now();
 416     /// let difference = sys_time.duration_since(sys_time)
 417     ///                          .expect("SystemTime::duration_since failed");
 418     /// println!("{:?}", difference);
 419     /// ```
 420     #[stable(feature = "time2", since = "1.8.0")]
 421     pub fn duration_since(&self, earlier: SystemTime)
 422                           -> Result<Duration, SystemTimeError> {
 423         self.0.sub_time(&earlier.0).map_err(SystemTimeError)
 424     }
 425
 426     /// Returns the amount of time elapsed since this system time was created.
 427     ///
 428     /// This function may fail as the underlying system clock is susceptible to
 429     /// drift and updates (e.g., the system clock could go backwards), so this
 430     /// function may not always succeed. If successful, [`Ok`]`(`[`Duration`]`)` is
 431     /// returned where the duration represents the amount of time elapsed from
 432     /// this time measurement to the current time.
 433     ///
 434     /// Returns an [`Err`] if `self` is later than the current system time, and
 435     /// the error contains how far from the current system time `self` is.
 436     ///
 437     /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
 438     /// [`Duration`]: ../../std/time/struct.Duration.html
 439     /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
 440     ///
 441     /// # Examples
 442     ///
 443     /// ```no_run
 444     /// use std::thread::sleep;
 445     /// use std::time::{Duration, SystemTime};
 446     ///
 447     /// let sys_time = SystemTime::now();
 448     /// let one_sec = Duration::from_secs(1);
 449     /// sleep(one_sec);
 450     /// assert!(sys_time.elapsed().unwrap() >= one_sec);
 451     /// ```
 452     #[stable(feature = "time2", since = "1.8.0")]
 453     pub fn elapsed(&self) -> Result<Duration, SystemTimeError> {
 454         SystemTime::now().duration_since(*self)
 455     }
 456
 457     /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
 458     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
 459     /// otherwise.
 460     #[stable(feature = "time_checked_add", since = "1.34.0")]
 461     pub fn checked_add(&self, duration: Duration) -> Option<SystemTime> {
 462         self.0.checked_add_duration(&duration).map(SystemTime)
 463     }
 464
 465     /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
 466     /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
 467     /// otherwise.
 468     #[stable(feature = "time_checked_add", since = "1.34.0")]
 469     pub fn checked_sub(&self, duration: Duration) -> Option<SystemTime> {
 470         self.0.checked_sub_duration(&duration).map(SystemTime)
 471     }
 472 }
 473
 474 #[stable(feature = "time2", since = "1.8.0")]
 475 impl Add<Duration> for SystemTime {
 476     type Output = SystemTime;
 477
 478     /// # Panics
 479     ///
 480     /// This function may panic if the resulting point in time cannot be represented by the
 481     /// underlying data structure. See [`checked_add`] for a version without panic.
 482     ///
 483     /// [`checked_add`]: ../../std/time/struct.SystemTime.html#method.checked_add
 484     fn add(self, dur: Duration) -> SystemTime {
 485         self.checked_add(dur)
 486             .expect("overflow when adding duration to instant")
 487     }
 488 }
 489
 490 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 491 impl AddAssign<Duration> for SystemTime {
 492     fn add_assign(&mut self, other: Duration) {
 493         *self = *self + other;
 494     }
 495 }
 496
 497 #[stable(feature = "time2", since = "1.8.0")]
 498 impl Sub<Duration> for SystemTime {
 499     type Output = SystemTime;
 500
 501     fn sub(self, dur: Duration) -> SystemTime {
 502         self.checked_sub(dur)
 503             .expect("overflow when subtracting duration from instant")
 504     }
 505 }
 506
 507 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
 508 impl SubAssign<Duration> for SystemTime {
 509     fn sub_assign(&mut self, other: Duration) {
 510         *self = *self - other;
 511     }
 512 }
 513
 514 #[stable(feature = "time2", since = "1.8.0")]
 515 impl fmt::Debug for SystemTime {
 516     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 517         self.0.fmt(f)
 518     }
 519 }
 520
 521 /// An anchor in time which can be used to create new `SystemTime` instances or
 522 /// learn about where in time a `SystemTime` lies.
 523 ///
 524 /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 525 /// respect to the system clock. Using `duration_since` on an existing
 526 /// [`SystemTime`] instance can tell how far away from this point in time a
 527 /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 528 /// [`SystemTime`] instance to represent another fixed point in time.
 529 ///
 530 /// [`SystemTime`]: ../../std/time/struct.SystemTime.html
 531 ///
 532 /// # Examples
 533 ///
 534 /// ```no_run
 535 /// use std::time::{SystemTime, UNIX_EPOCH};
 536 ///
 537 /// match SystemTime::now().duration_since(UNIX_EPOCH) {
 538 ///     Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
 539 ///     Err(_) => panic!("SystemTime before UNIX EPOCH!"),
 540 /// }
 541 /// ```
 542 #[stable(feature = "time2", since = "1.8.0")]
 543 pub const UNIX_EPOCH: SystemTime = SystemTime(time::UNIX_EPOCH);
 544
 545 impl SystemTimeError {
 546     /// Returns the positive duration which represents how far forward the
 547     /// second system time was from the first.
 548     ///
 549     /// A `SystemTimeError` is returned from the [`duration_since`] and [`elapsed`]
 550     /// methods of [`SystemTime`] whenever the second system time represents a point later
 551     /// in time than the `self` of the method call.
 552     ///
 553     /// [`duration_since`]: ../../std/time/struct.SystemTime.html#method.duration_since
 554     /// [`elapsed`]: ../../std/time/struct.SystemTime.html#method.elapsed
 555     /// [`SystemTime`]: ../../std/time/struct.SystemTime.html
 556     ///
 557     /// # Examples
 558     ///
 559     /// ```no_run
 560     /// use std::thread::sleep;
 561     /// use std::time::{Duration, SystemTime};
 562     ///
 563     /// let sys_time = SystemTime::now();
 564     /// sleep(Duration::from_secs(1));
 565     /// let new_sys_time = SystemTime::now();
 566     /// match sys_time.duration_since(new_sys_time) {
 567     ///     Ok(_) => {}
 568     ///     Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
 569     /// }
 570     /// ```
 571     #[stable(feature = "time2", since = "1.8.0")]
 572     pub fn duration(&self) -> Duration {
 573         self.0
 574     }
 575 }
 576
 577 #[stable(feature = "time2", since = "1.8.0")]
 578 impl Error for SystemTimeError {
 579     fn description(&self) -> &str { "other time was not earlier than self" }
 580 }
 581
 582 #[stable(feature = "time2", since = "1.8.0")]
 583 impl fmt::Display for SystemTimeError {
 584     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 585         write!(f, "second time provided was later than self")
 586     }
 587 }
 588
 589 impl FromInner<time::SystemTime> for SystemTime {
 590     fn from_inner(time: time::SystemTime) -> SystemTime {
 591         SystemTime(time)
 592     }
 593 }
 594
 595 #[cfg(test)]
 596 mod tests {
 597     use super::{Instant, SystemTime, Duration, UNIX_EPOCH};
 598
 599     macro_rules! assert_almost_eq {
 600         ($a:expr, $b:expr) => ({
 601             let (a, b) = ($a, $b);
 602             if a != b {
 603                 let (a, b) = if a > b {(a, b)} else {(b, a)};
 604                 assert!(a - Duration::new(0, 1000) <= b,
 605                         "{:?} is not almost equal to {:?}", a, b);
 606             }
 607         })
 608     }
 609
 610     #[test]
 611     fn instant_monotonic() {
 612         let a = Instant::now();
 613         let b = Instant::now();
 614         assert!(b >= a);
 615     }
 616
 617     #[test]
 618     fn instant_elapsed() {
 619         let a = Instant::now();
 620         a.elapsed();
 621     }
 622
 623     #[test]
 624     fn instant_math() {
 625         let a = Instant::now();
 626         let b = Instant::now();
 627         println!("a: {:?}", a);
 628         println!("b: {:?}", b);
 629         let dur = b.duration_since(a);
 630         println!("dur: {:?}", dur);
 631         assert_almost_eq!(b - dur, a);
 632         assert_almost_eq!(a + dur, b);
 633
 634         let second = Duration::new(1, 0);
 635         assert_almost_eq!(a - second + second, a);
 636         assert_almost_eq!(a.checked_sub(second).unwrap().checked_add(second).unwrap(), a);
 637
 638         // checked_add_duration will not panic on overflow
 639         let mut maybe_t = Some(Instant::now());
 640         let max_duration = Duration::from_secs(u64::max_value());
 641         // in case `Instant` can store `>= now + max_duration`.
 642         for _ in 0..2 {
 643             maybe_t = maybe_t.and_then(|t| t.checked_add(max_duration));
 644         }
 645         assert_eq!(maybe_t, None);
 646
 647         // checked_add_duration calculates the right time and will work for another year
 648         let year = Duration::from_secs(60 * 60 * 24 * 365);
 649         assert_eq!(a + year, a.checked_add(year).unwrap());
 650     }
 651
 652     #[test]
 653     fn instant_math_is_associative() {
 654         let now = Instant::now();
 655         let offset = Duration::from_millis(5);
 656         // Changing the order of instant math shouldn't change the results,
 657         // especially when the expression reduces to X + identity.
 658         assert_eq!((now + offset) - now, (now - now) + offset);
 659     }
 660
 661     #[test]
 662     #[should_panic]
 663     fn instant_duration_since_panic() {
 664         let a = Instant::now();
 665         (a - Duration::new(1, 0)).duration_since(a);
 666     }
 667
 668     #[test]
 669     fn instant_checked_duration_since_nopanic() {
 670         let now = Instant::now();
 671         let earlier = now - Duration::new(1, 0);
 672         let later = now + Duration::new(1, 0);
 673         assert_eq!(earlier.checked_duration_since(now), None);
 674         assert_eq!(later.checked_duration_since(now), Some(Duration::new(1, 0)));
 675         assert_eq!(now.checked_duration_since(now), Some(Duration::new(0, 0)));
 676     }
 677
 678     #[test]
 679     fn instant_saturating_duration_since_nopanic() {
 680         let a = Instant::now();
 681         let ret = (a - Duration::new(1, 0)).saturating_duration_since(a);
 682         assert_eq!(ret, Duration::new(0,0));
 683     }
 684
 685     #[test]
 686     fn system_time_math() {
 687         let a = SystemTime::now();
 688         let b = SystemTime::now();
 689         match b.duration_since(a) {
 690             Ok(dur) if dur == Duration::new(0, 0) => {
 691                 assert_almost_eq!(a, b);
 692             }
 693             Ok(dur) => {
 694                 assert!(b > a);
 695                 assert_almost_eq!(b - dur, a);
 696                 assert_almost_eq!(a + dur, b);
 697             }
 698             Err(dur) => {
 699                 let dur = dur.duration();
 700                 assert!(a > b);
 701                 assert_almost_eq!(b + dur, a);
 702                 assert_almost_eq!(a - dur, b);
 703             }
 704         }
 705
 706         let second = Duration::new(1, 0);
 707         assert_almost_eq!(a.duration_since(a - second).unwrap(), second);
 708         assert_almost_eq!(a.duration_since(a + second).unwrap_err()
 709                            .duration(), second);
 710
 711         assert_almost_eq!(a - second + second, a);
 712         assert_almost_eq!(a.checked_sub(second).unwrap().checked_add(second).unwrap(), a);
 713
 714         let one_second_from_epoch = UNIX_EPOCH + Duration::new(1, 0);
 715         let one_second_from_epoch2 = UNIX_EPOCH + Duration::new(0, 500_000_000)
 716             + Duration::new(0, 500_000_000);
 717         assert_eq!(one_second_from_epoch, one_second_from_epoch2);
 718
 719         // checked_add_duration will not panic on overflow
 720         let mut maybe_t = Some(SystemTime::UNIX_EPOCH);
 721         let max_duration = Duration::from_secs(u64::max_value());
 722         // in case `SystemTime` can store `>= UNIX_EPOCH + max_duration`.
 723         for _ in 0..2 {
 724             maybe_t = maybe_t.and_then(|t| t.checked_add(max_duration));
 725         }
 726         assert_eq!(maybe_t, None);
 727
 728         // checked_add_duration calculates the right time and will work for another year
 729         let year = Duration::from_secs(60 * 60 * 24 * 365);
 730         assert_eq!(a + year, a.checked_add(year).unwrap());
 731     }
 732
 733     #[test]
 734     fn system_time_elapsed() {
 735         let a = SystemTime::now();
 736         drop(a.elapsed());
 737     }
 738
 739     #[test]
 740     fn since_epoch() {
 741         let ts = SystemTime::now();
 742         let a = ts.duration_since(UNIX_EPOCH + Duration::new(1, 0)).unwrap();
 743         let b = ts.duration_since(UNIX_EPOCH).unwrap();
 744         assert!(b > a);
 745         assert_eq!(b - a, Duration::new(1, 0));
 746
 747         let thirty_years = Duration::new(1, 0) * 60 * 60 * 24 * 365 * 30;
 748
 749         // Right now for CI this test is run in an emulator, and apparently the
 750         // aarch64 emulator's sense of time is that we're still living in the
 751         // 70s.
 752         //
 753         // Otherwise let's assume that we're all running computers later than
 754         // 2000.
 755         if !cfg!(target_arch = "aarch64") {
 756             assert!(a > thirty_years);
 757         }
 758
 759         // let's assume that we're all running computers earlier than 2090.
 760         // Should give us ~70 years to fix this!
 761         let hundred_twenty_years = thirty_years * 4;
 762         assert!(a < hundred_twenty_years);
 763     }
 764 }