1 //! Temporal quantification.
5 //! There are multiple ways to create a new [`Duration`]:
8 //! # use std::time::Duration;
9 //! let five_seconds = Duration::from_secs(5);
10 //! assert_eq!(five_seconds, Duration::from_millis(5_000));
11 //! assert_eq!(five_seconds, Duration::from_micros(5_000_000));
12 //! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000));
14 //! let ten_seconds = Duration::from_secs(10);
15 //! let seven_nanos = Duration::from_nanos(7);
16 //! let total = ten_seconds + seven_nanos;
17 //! assert_eq!(total, Duration::new(10, 7));
20 //! Using [`Instant`] to calculate how long a function took to run:
22 //! ```ignore (incomplete)
23 //! let now = Instant::now();
25 //! // Calling a slow function, it may take a while
28 //! let elapsed_time = now.elapsed();
29 //! println!("Running slow_function() took {} seconds.", elapsed_time.as_secs());
32 #![stable(feature = "time", since = "1.3.0")]
38 use crate::error::Error;
40 use crate::ops::{Add, AddAssign, Sub, SubAssign};
42 use crate::sys_common::FromInner;
44 #[stable(feature = "time", since = "1.3.0")]
45 pub use core::time::Duration;
47 #[unstable(feature = "duration_checked_float", issue = "83400")]
48 pub use core::time::FromSecsError;
50 /// A measurement of a monotonically nondecreasing clock.
51 /// Opaque and useful only with [`Duration`].
53 /// Instants are always guaranteed to be no less than any previously measured
54 /// instant when created, and are often useful for tasks such as measuring
55 /// benchmarks or timing how long an operation takes.
57 /// Note, however, that instants are not guaranteed to be **steady**. In other
58 /// words, each tick of the underlying clock might not be the same length (e.g.
59 /// some seconds may be longer than others). An instant may jump forwards or
60 /// experience time dilation (slow down or speed up), but it will never go
63 /// Instants are opaque types that can only be compared to one another. There is
64 /// no method to get "the number of seconds" from an instant. Instead, it only
65 /// allows measuring the duration between two instants (or comparing two
68 /// The size of an `Instant` struct may vary depending on the target operating
74 /// use std::time::{Duration, Instant};
75 /// use std::thread::sleep;
78 /// let now = Instant::now();
80 /// // we sleep for 2 seconds
81 /// sleep(Duration::new(2, 0));
83 /// println!("{}", now.elapsed().as_secs());
87 /// # OS-specific behaviors
89 /// An `Instant` is a wrapper around system-specific types and it may behave
90 /// differently depending on the underlying operating system. For example,
91 /// the following snippet is fine on Linux but panics on macOS:
94 /// use std::time::{Instant, Duration};
96 /// let now = Instant::now();
97 /// let max_nanoseconds = u64::MAX / 1_000_000_000;
98 /// let duration = Duration::new(max_nanoseconds, 0);
99 /// println!("{:?}", now + duration);
102 /// # Underlying System calls
103 /// Currently, the following system calls are being used to get the current time using `now()`:
105 /// | Platform | System call |
106 /// |-----------|----------------------------------------------------------------------|
107 /// | SGX | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
108 /// | UNIX | [clock_gettime (Monotonic Clock)] |
109 /// | Darwin | [mach_absolute_time] |
110 /// | VXWorks | [clock_gettime (Monotonic Clock)] |
111 /// | SOLID | `get_tim` |
112 /// | WASI | [__wasi_clock_time_get (Monotonic Clock)] |
113 /// | Windows | [QueryPerformanceCounter] |
115 /// [QueryPerformanceCounter]: https://docs.microsoft.com/en-us/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter
116 /// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
117 /// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
118 /// [__wasi_clock_time_get (Monotonic Clock)]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#clock_time_get
119 /// [clock_gettime (Monotonic Clock)]: https://linux.die.net/man/3/clock_gettime
120 /// [mach_absolute_time]: https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/services/services.html
122 /// **Disclaimer:** These system calls might change over time.
124 /// > Note: mathematical operations like [`add`] may panic if the underlying
125 /// > structure cannot represent the new point in time.
127 /// [`add`]: Instant::add
128 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
129 #[stable(feature = "time2", since = "1.8.0")]
130 pub struct Instant(time::Instant);
132 /// A measurement of the system clock, useful for talking to
133 /// external entities like the file system or other processes.
135 /// Distinct from the [`Instant`] type, this time measurement **is not
136 /// monotonic**. This means that you can save a file to the file system, then
137 /// save another file to the file system, **and the second file has a
138 /// `SystemTime` measurement earlier than the first**. In other words, an
139 /// operation that happens after another operation in real time may have an
140 /// earlier `SystemTime`!
142 /// Consequently, comparing two `SystemTime` instances to learn about the
143 /// duration between them returns a [`Result`] instead of an infallible [`Duration`]
144 /// to indicate that this sort of time drift may happen and needs to be handled.
146 /// Although a `SystemTime` cannot be directly inspected, the [`UNIX_EPOCH`]
147 /// constant is provided in this module as an anchor in time to learn
148 /// information about a `SystemTime`. By calculating the duration from this
149 /// fixed point in time, a `SystemTime` can be converted to a human-readable time,
150 /// or perhaps some other string representation.
152 /// The size of a `SystemTime` struct may vary depending on the target operating
158 /// use std::time::{Duration, SystemTime};
159 /// use std::thread::sleep;
162 /// let now = SystemTime::now();
164 /// // we sleep for 2 seconds
165 /// sleep(Duration::new(2, 0));
166 /// match now.elapsed() {
169 /// println!("{}", elapsed.as_secs());
172 /// // an error occurred!
173 /// println!("Error: {:?}", e);
179 /// # Underlying System calls
180 /// Currently, the following system calls are being used to get the current time using `now()`:
182 /// | Platform | System call |
183 /// |-----------|----------------------------------------------------------------------|
184 /// | SGX | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
185 /// | UNIX | [clock_gettime (Realtime Clock)] |
186 /// | Darwin | [gettimeofday] |
187 /// | VXWorks | [clock_gettime (Realtime Clock)] |
188 /// | SOLID | `SOLID_RTC_ReadTime` |
189 /// | WASI | [__wasi_clock_time_get (Realtime Clock)] |
190 /// | Windows | [GetSystemTimePreciseAsFileTime] / [GetSystemTimeAsFileTime] |
192 /// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
193 /// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
194 /// [gettimeofday]: https://man7.org/linux/man-pages/man2/gettimeofday.2.html
195 /// [clock_gettime (Realtime Clock)]: https://linux.die.net/man/3/clock_gettime
196 /// [__wasi_clock_time_get (Realtime Clock)]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#clock_time_get
197 /// [GetSystemTimePreciseAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime
198 /// [GetSystemTimeAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime
200 /// **Disclaimer:** These system calls might change over time.
202 /// > Note: mathematical operations like [`add`] may panic if the underlying
203 /// > structure cannot represent the new point in time.
205 /// [`add`]: SystemTime::add
206 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
207 #[stable(feature = "time2", since = "1.8.0")]
208 pub struct SystemTime(time::SystemTime);
210 /// An error returned from the `duration_since` and `elapsed` methods on
211 /// `SystemTime`, used to learn how far in the opposite direction a system time
217 /// use std::thread::sleep;
218 /// use std::time::{Duration, SystemTime};
220 /// let sys_time = SystemTime::now();
221 /// sleep(Duration::from_secs(1));
222 /// let new_sys_time = SystemTime::now();
223 /// match sys_time.duration_since(new_sys_time) {
225 /// Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
228 #[derive(Clone, Debug)]
229 #[stable(feature = "time2", since = "1.8.0")]
230 pub struct SystemTimeError(Duration);
233 /// Returns an instant corresponding to "now".
238 /// use std::time::Instant;
240 /// let now = Instant::now();
243 #[stable(feature = "time2", since = "1.8.0")]
244 pub fn now() -> Instant {
245 let os_now = time::Instant::now();
247 // And here we come upon a sad state of affairs. The whole point of
248 // `Instant` is that it's monotonically increasing. We've found in the
249 // wild, however, that it's not actually monotonically increasing for
250 // one reason or another. These appear to be OS and hardware level bugs,
251 // and there's not really a whole lot we can do about them. Here's a
252 // taste of what we've found:
254 // * #48514 - OpenBSD, x86_64
255 // * #49281 - linux arm64 and s390x
256 // * #51648 - windows, x86
257 // * #56560 - windows, x86_64, AWS
258 // * #56612 - windows, x86, vm (?)
259 // * #56940 - linux, arm64
260 // * https://bugzilla.mozilla.org/show_bug.cgi?id=1487778 - a similar
263 // It seems that this just happens a lot in the wild.
264 // We're seeing panics across various platforms where consecutive calls
265 // to `Instant::now`, such as via the `elapsed` function, are panicking
266 // as they're going backwards. Placed here is a last-ditch effort to try
267 // to fix things up. We keep a global "latest now" instance which is
268 // returned instead of what the OS says if the OS goes backwards.
270 // To hopefully mitigate the impact of this, a few platforms are
271 // excluded as "these at least haven't gone backwards yet".
273 // While issues have been seen on arm64 platforms the Arm architecture
274 // requires that the counter monotonically increases and that it must
275 // provide a uniform view of system time (e.g. it must not be possible
276 // for a core to recieve a message from another core with a time stamp
277 // and observe time going backwards (ARM DDI 0487G.b D11.1.2). While
278 // there have been a few 64bit SoCs that have bugs which cause time to
279 // not monoticially increase, these have been fixed in the Linux kernel
280 // and we shouldn't penalize all Arm SoCs for those who refuse to
281 // update their kernels:
282 // SUN50I_ERRATUM_UNKNOWN1 - Allwinner A64 / Pine A64 - fixed in 5.1
283 // FSL_ERRATUM_A008585 - Freescale LS2080A/LS1043A - fixed in 4.10
284 // HISILICON_ERRATUM_161010101 - Hisilicon 1610 - fixed in 4.11
285 // ARM64_ERRATUM_858921 - Cortex A73 - fixed in 4.12
286 if time::Instant::actually_monotonic() {
287 return Instant(os_now);
290 Instant(monotonic::monotonize(os_now))
293 /// Returns the amount of time elapsed from another instant to this one.
297 /// This function will panic if `earlier` is later than `self`.
302 /// use std::time::{Duration, Instant};
303 /// use std::thread::sleep;
305 /// let now = Instant::now();
306 /// sleep(Duration::new(1, 0));
307 /// let new_now = Instant::now();
308 /// println!("{:?}", new_now.duration_since(now));
311 #[stable(feature = "time2", since = "1.8.0")]
312 pub fn duration_since(&self, earlier: Instant) -> Duration {
313 self.0.checked_sub_instant(&earlier.0).expect("supplied instant is later than self")
316 /// Returns the amount of time elapsed from another instant to this one,
317 /// or None if that instant is later than this one.
322 /// use std::time::{Duration, Instant};
323 /// use std::thread::sleep;
325 /// let now = Instant::now();
326 /// sleep(Duration::new(1, 0));
327 /// let new_now = Instant::now();
328 /// println!("{:?}", new_now.checked_duration_since(now));
329 /// println!("{:?}", now.checked_duration_since(new_now)); // None
332 #[stable(feature = "checked_duration_since", since = "1.39.0")]
333 pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
334 self.0.checked_sub_instant(&earlier.0)
337 /// Returns the amount of time elapsed from another instant to this one,
338 /// or zero duration if that instant is later than this one.
343 /// use std::time::{Duration, Instant};
344 /// use std::thread::sleep;
346 /// let now = Instant::now();
347 /// sleep(Duration::new(1, 0));
348 /// let new_now = Instant::now();
349 /// println!("{:?}", new_now.saturating_duration_since(now));
350 /// println!("{:?}", now.saturating_duration_since(new_now)); // 0ns
353 #[stable(feature = "checked_duration_since", since = "1.39.0")]
354 pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
355 self.checked_duration_since(earlier).unwrap_or_default()
358 /// Returns the amount of time elapsed since this instant was created.
362 /// This function may panic if the current time is earlier than this
363 /// instant, which is something that can happen if an `Instant` is
364 /// produced synthetically.
369 /// use std::thread::sleep;
370 /// use std::time::{Duration, Instant};
372 /// let instant = Instant::now();
373 /// let three_secs = Duration::from_secs(3);
374 /// sleep(three_secs);
375 /// assert!(instant.elapsed() >= three_secs);
378 #[stable(feature = "time2", since = "1.8.0")]
379 pub fn elapsed(&self) -> Duration {
380 Instant::now() - *self
383 /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
384 /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
386 #[stable(feature = "time_checked_add", since = "1.34.0")]
387 pub fn checked_add(&self, duration: Duration) -> Option<Instant> {
388 self.0.checked_add_duration(&duration).map(Instant)
391 /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
392 /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
394 #[stable(feature = "time_checked_add", since = "1.34.0")]
395 pub fn checked_sub(&self, duration: Duration) -> Option<Instant> {
396 self.0.checked_sub_duration(&duration).map(Instant)
400 #[stable(feature = "time2", since = "1.8.0")]
401 impl Add<Duration> for Instant {
402 type Output = Instant;
406 /// This function may panic if the resulting point in time cannot be represented by the
407 /// underlying data structure. See [`Instant::checked_add`] for a version without panic.
408 fn add(self, other: Duration) -> Instant {
409 self.checked_add(other).expect("overflow when adding duration to instant")
413 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
414 impl AddAssign<Duration> for Instant {
415 fn add_assign(&mut self, other: Duration) {
416 *self = *self + other;
420 #[stable(feature = "time2", since = "1.8.0")]
421 impl Sub<Duration> for Instant {
422 type Output = Instant;
424 fn sub(self, other: Duration) -> Instant {
425 self.checked_sub(other).expect("overflow when subtracting duration from instant")
429 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
430 impl SubAssign<Duration> for Instant {
431 fn sub_assign(&mut self, other: Duration) {
432 *self = *self - other;
436 #[stable(feature = "time2", since = "1.8.0")]
437 impl Sub<Instant> for Instant {
438 type Output = Duration;
440 fn sub(self, other: Instant) -> Duration {
441 self.duration_since(other)
445 #[stable(feature = "time2", since = "1.8.0")]
446 impl fmt::Debug for Instant {
447 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
453 /// An anchor in time which can be used to create new `SystemTime` instances or
454 /// learn about where in time a `SystemTime` lies.
456 /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
457 /// respect to the system clock. Using `duration_since` on an existing
458 /// `SystemTime` instance can tell how far away from this point in time a
459 /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
460 /// `SystemTime` instance to represent another fixed point in time.
465 /// use std::time::SystemTime;
467 /// match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) {
468 /// Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
469 /// Err(_) => panic!("SystemTime before UNIX EPOCH!"),
472 #[stable(feature = "assoc_unix_epoch", since = "1.28.0")]
473 pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH;
475 /// Returns the system time corresponding to "now".
480 /// use std::time::SystemTime;
482 /// let sys_time = SystemTime::now();
485 #[stable(feature = "time2", since = "1.8.0")]
486 pub fn now() -> SystemTime {
487 SystemTime(time::SystemTime::now())
490 /// Returns the amount of time elapsed from an earlier point in time.
492 /// This function may fail because measurements taken earlier are not
493 /// guaranteed to always be before later measurements (due to anomalies such
494 /// as the system clock being adjusted either forwards or backwards).
495 /// [`Instant`] can be used to measure elapsed time without this risk of failure.
497 /// If successful, <code>[Ok]\([Duration])</code> is returned where the duration represents
498 /// the amount of time elapsed from the specified measurement to this one.
500 /// Returns an [`Err`] if `earlier` is later than `self`, and the error
501 /// contains how far from `self` the time is.
506 /// use std::time::SystemTime;
508 /// let sys_time = SystemTime::now();
509 /// let new_sys_time = SystemTime::now();
510 /// let difference = new_sys_time.duration_since(sys_time)
511 /// .expect("Clock may have gone backwards");
512 /// println!("{:?}", difference);
514 #[stable(feature = "time2", since = "1.8.0")]
515 pub fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError> {
516 self.0.sub_time(&earlier.0).map_err(SystemTimeError)
519 /// Returns the difference between the clock time when this
520 /// system time was created, and the current clock time.
522 /// This function may fail as the underlying system clock is susceptible to
523 /// drift and updates (e.g., the system clock could go backwards), so this
524 /// function might not always succeed. If successful, <code>[Ok]\([Duration])</code> is
525 /// returned where the duration represents the amount of time elapsed from
526 /// this time measurement to the current time.
528 /// To measure elapsed time reliably, use [`Instant`] instead.
530 /// Returns an [`Err`] if `self` is later than the current system time, and
531 /// the error contains how far from the current system time `self` is.
536 /// use std::thread::sleep;
537 /// use std::time::{Duration, SystemTime};
539 /// let sys_time = SystemTime::now();
540 /// let one_sec = Duration::from_secs(1);
542 /// assert!(sys_time.elapsed().unwrap() >= one_sec);
544 #[stable(feature = "time2", since = "1.8.0")]
545 pub fn elapsed(&self) -> Result<Duration, SystemTimeError> {
546 SystemTime::now().duration_since(*self)
549 /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
550 /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
552 #[stable(feature = "time_checked_add", since = "1.34.0")]
553 pub fn checked_add(&self, duration: Duration) -> Option<SystemTime> {
554 self.0.checked_add_duration(&duration).map(SystemTime)
557 /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
558 /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None`
560 #[stable(feature = "time_checked_add", since = "1.34.0")]
561 pub fn checked_sub(&self, duration: Duration) -> Option<SystemTime> {
562 self.0.checked_sub_duration(&duration).map(SystemTime)
566 #[stable(feature = "time2", since = "1.8.0")]
567 impl Add<Duration> for SystemTime {
568 type Output = SystemTime;
572 /// This function may panic if the resulting point in time cannot be represented by the
573 /// underlying data structure. See [`SystemTime::checked_add`] for a version without panic.
574 fn add(self, dur: Duration) -> SystemTime {
575 self.checked_add(dur).expect("overflow when adding duration to instant")
579 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
580 impl AddAssign<Duration> for SystemTime {
581 fn add_assign(&mut self, other: Duration) {
582 *self = *self + other;
586 #[stable(feature = "time2", since = "1.8.0")]
587 impl Sub<Duration> for SystemTime {
588 type Output = SystemTime;
590 fn sub(self, dur: Duration) -> SystemTime {
591 self.checked_sub(dur).expect("overflow when subtracting duration from instant")
595 #[stable(feature = "time_augmented_assignment", since = "1.9.0")]
596 impl SubAssign<Duration> for SystemTime {
597 fn sub_assign(&mut self, other: Duration) {
598 *self = *self - other;
602 #[stable(feature = "time2", since = "1.8.0")]
603 impl fmt::Debug for SystemTime {
604 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
609 /// An anchor in time which can be used to create new `SystemTime` instances or
610 /// learn about where in time a `SystemTime` lies.
612 /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
613 /// respect to the system clock. Using `duration_since` on an existing
614 /// [`SystemTime`] instance can tell how far away from this point in time a
615 /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
616 /// [`SystemTime`] instance to represent another fixed point in time.
621 /// use std::time::{SystemTime, UNIX_EPOCH};
623 /// match SystemTime::now().duration_since(UNIX_EPOCH) {
624 /// Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
625 /// Err(_) => panic!("SystemTime before UNIX EPOCH!"),
628 #[stable(feature = "time2", since = "1.8.0")]
629 pub const UNIX_EPOCH: SystemTime = SystemTime(time::UNIX_EPOCH);
631 impl SystemTimeError {
632 /// Returns the positive duration which represents how far forward the
633 /// second system time was from the first.
635 /// A `SystemTimeError` is returned from the [`SystemTime::duration_since`]
636 /// and [`SystemTime::elapsed`] methods whenever the second system time
637 /// represents a point later in time than the `self` of the method call.
642 /// use std::thread::sleep;
643 /// use std::time::{Duration, SystemTime};
645 /// let sys_time = SystemTime::now();
646 /// sleep(Duration::from_secs(1));
647 /// let new_sys_time = SystemTime::now();
648 /// match sys_time.duration_since(new_sys_time) {
650 /// Err(e) => println!("SystemTimeError difference: {:?}", e.duration()),
654 #[stable(feature = "time2", since = "1.8.0")]
655 pub fn duration(&self) -> Duration {
660 #[stable(feature = "time2", since = "1.8.0")]
661 impl Error for SystemTimeError {
663 fn description(&self) -> &str {
664 "other time was not earlier than self"
668 #[stable(feature = "time2", since = "1.8.0")]
669 impl fmt::Display for SystemTimeError {
670 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
671 write!(f, "second time provided was later than self")
675 impl FromInner<time::SystemTime> for SystemTime {
676 fn from_inner(time: time::SystemTime) -> SystemTime {