Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Standard Library Modules

Rust Instant and SystemTime types

Reference for std::time::Instant and SystemTime: monotonic timing with elapsed, UNIX_EPOCH, duration_since errors, checked arithmetic and when to use which clock.

Rust has two clocks in std::time. Instant is a monotonic clock: it never goes backwards and is meant for measuring how long something took. You cannot turn an Instant into a date; its starting point is unspecified. SystemTime is the wall clock: it can be converted to and from a Unix timestamp, but the user or a network time service can change it at any moment, so it can jump forward or backward.

Use Instant for timeouts, benchmarks and rate limits. Use SystemTime for file modification times, timestamps in logs and anything that must mean the same thing after a restart.

Rust
use std::time::Instant;

let start = Instant::now();
let elapsed = start.elapsed(); // a Duration

Try it

Rust Measuring with Instant

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust SystemTime and UNIX_EPOCH

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
impl Instant {
    pub fn now() -> Instant;
    pub fn elapsed(&self) -> Duration;
    pub fn duration_since(&self, earlier: Instant) -> Duration;
    pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration>;
    pub fn saturating_duration_since(&self, earlier: Instant) -> Duration;
    pub fn checked_add(&self, d: Duration) -> Option<Instant>;
    pub fn checked_sub(&self, d: Duration) -> Option<Instant>;
}

impl SystemTime {
    pub const UNIX_EPOCH: SystemTime;
    pub fn now() -> SystemTime;
    pub fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError>;
    pub fn elapsed(&self) -> Result<Duration, SystemTimeError>;
    pub fn checked_add(&self, d: Duration) -> Option<SystemTime>;
    pub fn checked_sub(&self, d: Duration) -> Option<SystemTime>;
}

pub const UNIX_EPOCH: SystemTime; // std::time::UNIX_EPOCH
Name Description
earlier The other point in time. For Instant, the result is the time from earlier to self.
d The Duration to add or subtract.

Returns. Instant methods return a plain Duration. SystemTime methods return Result, because the wall clock may have gone backwards; SystemTimeError::duration() gives the (positive) size of the difference.

Errors and panics.

  • Instant::duration_since returns zero if earlier is actually later (since Rust 1.60); it no longer panics. Use checked_duration_since if you want to detect that case.
  • Instant + Duration and Instant - Duration panic if the result cannot be represented. checked_add and checked_sub return None instead.
  • SystemTime::duration_since returns Err when earlier is later than self.

Usage notes

  • Never print or compare raw Instant values across processes. They have no meaning outside the running program. The Debug output differs per platform.
  • Monotonic is not the same as "includes sleep". On some platforms the monotonic clock pauses while the machine is suspended, on others it keeps counting. Do not rely on either.
  • SystemTime is for timestamps. To store one, convert with duration_since(UNIX_EPOCH) and keep the seconds. To build one, use UNIX_EPOCH + Duration::from_secs(n).
  • Precision depends on the OS. Windows and macOS may round SystemTime to 100 ns or 1 ยตs; Linux gives nanoseconds.
  • No calendar. There is no way to ask std for the year, month or time zone. Convert the timestamp with a date-time crate, or write the civil-date algorithm yourself (see the lesson).
  • Measuring code. Compile with optimizations, run several times and use std::hint::black_box so the optimizer cannot delete the work. For serious benchmarks use a harness.
  • Testing. Code that calls now() directly is hard to test. Pass the clock in, or pass the current Instant or SystemTime as a parameter.
  • File times. Metadata::modified() returns a SystemTime; compare with duration_since and handle the Err case.