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.
use std::time::Instant; let start = Instant::now(); let elapsed = start.elapsed(); // a Duration
Try it
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.
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
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_sincereturns zero ifearlieris actually later (since Rust 1.60); it no longer panics. Usechecked_duration_sinceif you want to detect that case.Instant + DurationandInstant - Durationpanic if the result cannot be represented.checked_addandchecked_subreturnNoneinstead.SystemTime::duration_sincereturnsErrwhenearlieris later thanself.
Usage notes
- Never print or compare raw
Instantvalues across processes. They have no meaning outside the running program. TheDebugoutput 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.
SystemTimeis for timestamps. To store one, convert withduration_since(UNIX_EPOCH)and keep the seconds. To build one, useUNIX_EPOCH + Duration::from_secs(n).- Precision depends on the OS. Windows and macOS may round
SystemTimeto 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_boxso 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 currentInstantorSystemTimeas a parameter. - File times.
Metadata::modified()returns aSystemTime; compare withduration_sinceand handle theErrcase.