diff options
| -rw-r--r-- | tokio/src/time/instant.rs | 28 |
1 files changed, 26 insertions, 2 deletions
diff --git a/tokio/src/time/instant.rs b/tokio/src/time/instant.rs index e14a3004..f4d6eacb 100644 --- a/tokio/src/time/instant.rs +++ b/tokio/src/time/instant.rs @@ -4,8 +4,32 @@ use std::fmt; use std::ops; use std::time::Duration; -/// A measurement of the system clock, useful for talking to -/// external entities like the file system or other processes. +/// A measurement of a monotonically nondecreasing clock. +/// Opaque and useful only with `Duration`. +/// +/// Instants are always guaranteed to be no less than any previously measured +/// instant when created, and are often useful for tasks such as measuring +/// benchmarks or timing how long an operation takes. +/// +/// Note, however, that instants are not guaranteed to be **steady**. In other +/// words, each tick of the underlying clock may not be the same length (e.g. +/// some seconds may be longer than others). An instant may jump forwards or +/// experience time dilation (slow down or speed up), but it will never go +/// backwards. +/// +/// Instants are opaque types that can only be compared to one another. There is +/// no method to get "the number of seconds" from an instant. Instead, it only +/// allows measuring the duration between two instants (or comparing two +/// instants). +/// +/// The size of an `Instant` struct may vary depending on the target operating +/// system. +/// +/// # Note +/// +/// This type wraps the inner `std` variant and is used to align the Tokio +/// clock for uses of `now()`. This can be useful for testing where you can +/// take advantage of `time::pause()` and `time::advance()`. #[derive(Clone, Copy, Eq, PartialEq, PartialOrd, Ord, Hash)] pub struct Instant { std: std::time::Instant, |