Struct TestClock

Source

pub struct TestClock { /* private fields */ }

Available on crate feature test-clock and (crate features test-clock) only.

Expand description

Owns a clock that moves only when advanced, for tests.

Self::clock hands out handles that read and sleep on its time. Only the owner moves it, through methods that take &mut self, so each test clock has one driver.

Implementations§

Source §

impl TestClock

Source

pub fn new() -> Self

Creates a stopped clock at the current real monotonic and wall times.

Source

pub fn clock(&self) -> Clock

Returns a handle that reads and sleeps on this clock.

Source

pub fn advance(&mut self, by: Duration)

Moves both times forward by by, waking the sleeps and deadline waits it reaches and firing its due timers.

Returns once the reached waits are woken and the due timers hold their messages, without waiting for any thread to act. Other waits keep waiting, since an advance never counts as a notification. A zero advance does nothing.

§Panics

Panics if either time would overflow, before changing either one.

Source

pub fn advance_to(&mut self, target: Instant)

Moves monotonic time to target and wall time by the same amount, waking the sleeps and deadline waits it reaches and firing its due timers.

Returns once the reached waits are woken and the due timers hold their messages, without waiting for any thread to act. Other waits keep waiting, since an advance never counts as a notification. Advancing to the current time does nothing.

§Panics

Panics if target is before now or wall time would overflow. Neither time changes after a panic.

Source

pub fn set_system_time(&mut self, time: SystemTime)

Sets wall time forwards or backwards without moving monotonic time.

This wakes no waits and fires no timers, since deadlines use monotonic time.

Source

pub fn wait_registered(&self, count: usize)

Blocks until at least count clock sleeps or condvar waits are registered, timed or not.

A wait stays registered from the moment it starts waiting until it returns. So the count includes a thread that a notification or an advance has woken but that has not run yet. Threads blocked in crossbeam receives, selects or mutexes, or busy outside clock waits, do not count. An earlier registration counts too, so the count proves no progress on its own. Nothing bounds the wait, so run tests under a runner with a per-test timeout, since cargo test alone never stops a hung test.

Source

pub fn wait_parked(&self, count: usize)

Blocks until at least count registered waits are parked, with their deadlines unreached or absent, and no notification on this clock is outstanding.

A notification stays outstanding until every wait it ended has returned. So a woken thread that has not run yet holds the barrier, on whichever condvar of this clock it waits.

The count must cover every worker the test expects to park, and the test must control the work they receive. Threads blocked in crossbeam receives, selects or mutexes, or busy outside clock waits, are invisible to it, and a worker that exits never counts again. Nothing bounds the wait, so run tests under a runner with a per-test timeout.

Source

pub fn wait_timers(&self, count: usize)

Available on crate feature crossbeam only.

Blocks until at least count timers are armed on this clock and unfired.

A waiting receive’s timer counts, and so does a timer whose receiver was dropped. A timer armed earlier counts too, so the count proves no progress on its own. Nothing bounds the wait, so run tests under a runner with a per-test timeout, since cargo test alone never stops a hung test.

Source

pub fn next_deadline(&self) -> Option<Instant>

Returns the earliest deadline among this clock’s registered sleeps, deadline waits and unfired timers, or None when there is none.

A timed wait stays listed until it stops waiting, so one an advance reaches stays listed until its thread runs, and the result is then the current time. Await an advance’s effect before reading the next deadline. A timer leaves the list when it fires.