Struct std::time::Instant

pub struct Instant(_);

单调非递减时钟的度量。 不透明且仅对 Duration 有用。

除 platform bugs 外，时刻始终保证不低于任何先前测量的创建时的时刻，并且对于诸如测量基准或计时操作需要多长时间等任务通常很有用。

但是请注意，不能保证 instants 是稳定的。换句话说，底层时钟的每个滴答声的长度可能不同 (例如 几秒钟可能比其他更长)。瞬间可能会向前跳跃或经历时间膨胀 (减速或加速)，但永远不会向后退。

即时消息是不透明的类型，只能相互比较。没有方法可以立即获取 “秒数”。 相反，它仅允许测量两个瞬间之间的持续时间 (或比较两个瞬间)。

Instant 结构体的大小可能会因目标操作系统而异。

Example:

use std::time::{Duration, Instant};
use std::thread::sleep;

fn main() {
   let now = Instant::now();

   // 我们睡了 2 秒钟
   sleep(Duration::new(2, 0));
   // 它打印 '2'
   println!("{}", now.elapsed().as_secs());
}

特定于操作系统的行为

Instant 是系统特定类型的包装器，根据底层操作系统的不同，它的行为可能会有所不同。 例如，以下代码段在 Linux 上很好，但在 macOS 上为 panics：

use std::time::{Instant, Duration};

let now = Instant::now();
let max_seconds = u64::MAX / 1_000_000_000;
let duration = Duration::new(max_seconds, 0);
println!("{:?}", now + duration);

底层系统调用

以下系统调用是 now() 使用 currently 来找出当前时间:

Platform	System call
SGX	insecure_time usercall. More information on timekeeping in SGX
UNIX	clock_gettime (Monotonic Clock)
Darwin	mach_absolute_time
VXWorks	clock_gettime (Monotonic Clock)
SOLID	get_tim
WASI	__wasi_clock_time_get (Monotonic Clock)
Windows	QueryPerformanceCounter

免责声明: 这些系统调用可能会随时间变化。

Note: 如果 add 的数学运算可能是 panic 结构体不能代表新的时间点。

Monotonicity

在所有平台上，Instant 将尝试使用保证单调行为 (如果可用) 的 OS API，所有 tier 1 平台都是这种情况。 在实践中，这种保证在极少数情况下会被硬件、虚拟化或操作系统错误破坏。 为了解决这些错误和不提供单调时钟的平台，duration_since、elapsed 和 sub 饱和为零。 在较旧的 Rust 版本中，这反而会导致 panic。 checked_duration_since 可用于检测和处理违反单调性或以错误顺序减去 即时 的情况。

这种变通方法掩盖了早期和后期瞬间意外交换的编程错误。出于这个原因，未来的 rust 版本可能会重新引入 panic。

Implementations

impl Instant

pub fn now() -> Instant

返回对应于 “now” 的瞬间。

Examples

use std::time::Instant;

let now = Instant::now();

pub fn duration_since(&self, earlier: Instant) -> Duration

返回从另一时刻到该时刻所经过的时间，如果该时刻晚于该时刻，则返回零持续时间。

Panics

当 earlier 晚于 self 时，以前的 rust 版本会出现 panic。目前这种方法已经饱和。 未来的版本在某些情况下可能会重新引入 panic。 请参见 Monotonicity。

Examples

use std::time::{Duration, Instant};
use std::thread::sleep;

let now = Instant::now();
sleep(Duration::new(1, 0));
let new_now = Instant::now();
println!("{:?}", new_now.duration_since(now));
println!("{:?}", now.duration_since(new_now)); // 0ns

pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration>

返回从另一个时刻到该时刻所经过的时间; 如果该时刻晚于该时刻，则返回 None。

由于 monotonicity bugs，即使在传递的 Instant 的正确逻辑顺序下，此方法也可以返回 None。

Examples

use std::time::{Duration, Instant};
use std::thread::sleep;

let now = Instant::now();
sleep(Duration::new(1, 0));
let new_now = Instant::now();
println!("{:?}", new_now.checked_duration_since(now));
println!("{:?}", now.checked_duration_since(new_now)); // None

pub fn saturating_duration_since(&self, earlier: Instant) -> Duration

返回从另一时刻到该时刻所经过的时间，如果该时刻晚于该时刻，则返回零持续时间。

Examples

use std::time::{Duration, Instant};
use std::thread::sleep;

let now = Instant::now();
sleep(Duration::new(1, 0));
let new_now = Instant::now();
println!("{:?}", new_now.saturating_duration_since(now));
println!("{:?}", now.saturating_duration_since(new_now)); // 0ns

pub fn elapsed(&self) -> Duration

返回自该时刻以来经过的时间量。

Panics

当前时间早于自己时，以前的 rust 版本会出现 panic。目前，在这种情况下，此方法返回的 Duration 为零。 未来的版本可能会重新引入 panic。 请参见 Monotonicity。

Examples

use std::thread::sleep;
use std::time::{Duration, Instant};

let instant = Instant::now();
let three_secs = Duration::from_secs(3);
sleep(three_secs);
assert!(instant.elapsed() >= three_secs);

pub fn checked_add(&self, duration: Duration) -> Option<Instant>

如果 t 可以表示为 Instant (这意味着它在底层数据结构的边界内)，则返回 Some(t)，其中 t 是时间 self + duration，否则返回 None。

pub fn checked_sub(&self, duration: Duration) -> Option<Instant>

如果 t 可以表示为 Instant (表示它在底层数据结构体的边界之内)，则返回 Some(t)，其中 t 是 self - duration 的时间，否则返回 None。

Trait Implementations

impl Add<Duration> for Instant

fn add(self, other: Duration) -> Instant

Panics

如果生成的时间点无法由底层数据结构表示，则此函数可能出现 panic。 没有 panic 的版本，请参见 Instant::checked_add。

type Output = Instant

应用 + 运算符后的结果类型。

impl AddAssign<Duration> for Instant

fn add_assign(&mut self, other: Duration)

执行 += 操作。

impl Clone for Instant

fn clone(&self) -> Instant

返回值的副本。

fn clone_from(&mut self, source: &Self)

从 source 执行复制分配。

impl Debug for Instant

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化程序格式化该值。

impl Hash for Instant

fn hash<__H: Hasher>(&self, state: &mut __H)

将该值输入给定的 Hasher。

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

将这种类型的切片送入给定的 Hasher 中。

impl Ord for Instant

fn cmp(&self, other: &Instant) -> Ordering

此方法返回 self 和 other 之间的 Ordering。

fn max(self, other: Self) -> Selfwhere Self: Sized,

比较并返回两个值中的最大值。

fn min(self, other: Self) -> Selfwhere Self: Sized,

比较并返回两个值中的最小值。

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

将值限制在某个时间间隔内。

impl PartialEq<Instant> for Instant

fn eq(&self, other: &Instant) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &Rhs) -> bool

此方法测试 !=。 默认实现几乎总是足够的，并且不应在没有充分理由的情况下被覆盖。

impl PartialOrd<Instant> for Instant

fn partial_cmp(&self, other: &Instant) -> Option<Ordering>

如果存在，则此方法返回 self 和 other 值之间的顺序。

fn lt(&self, other: &Rhs) -> bool

此方法测试的内容少于 (对于 self 和 other)，并且由 < 操作员使用。

fn le(&self, other: &Rhs) -> bool

此方法测试小于或等于 (对于 self 和 other)，并且由 <= 运算符使用。

fn gt(&self, other: &Rhs) -> bool

此方法测试大于 (对于 self 和 other)，并且由 > 操作员使用。

fn ge(&self, other: &Rhs) -> bool

此方法测试是否大于或等于 (对于 self 和 other)，并且由 >= 运算符使用。

impl Sub<Duration> for Instant

type Output = Instant

应用 - 运算符后的结果类型。

fn sub(self, other: Duration) -> Instant

执行 - 操作。

impl Sub<Instant> for Instant

fn sub(self, other: Instant) -> Duration

返回从另一时刻到该时刻所经过的时间，如果该时刻晚于该时刻，则返回零持续时间。

Panics

当 other 晚于 self 时，以前的 rust 版本会出现 panic。目前这种方法已经饱和。 未来的版本在某些情况下可能会重新引入 panic。 请参见 Monotonicity。

type Output = Duration

应用 - 运算符后的结果类型。

impl SubAssign<Duration> for Instant

fn sub_assign(&mut self, other: Duration)

执行 -= 操作。

impl Copy for Instant

impl Eq for Instant

impl StructuralEq for Instant

impl StructuralPartialEq for Instant