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