Struct SimpleMockTimeProvider

pub struct SimpleMockTimeProvider { /* private fields */ }

Simple provider of simulated time

Maintains a mocked view of the current Instant and SystemTime.

The simulated time advances only when explicitly instructed, by calling .advance().

The wallclock time can be warped with .jump_wallclock(), allowing simulation of wall clock non-monotonicity.

Panics and aborts

Panics on time under/overflow.

May cause an abort if the SimpleMockTimeProvider implementation contains bugs.

Implementations

impl SimpleMockTimeProvider

pub fn new(now: Instant, wallclock: SystemTime) -> Self

Return a new mock time provider starting at a specified point in time

pub fn from_real() -> Self

Return a new mock time provider starting at the current actual (non-mock) time

Like any SimpleMockTimeProvider, the time is frozen and only changes due to calls to advance.

pub fn from_wallclock(wallclock: SystemTime) -> Self

Return a new mock time provider starting at a specified wallclock time

The monotonic time (Instant) starts at the current actual (non-mock) time. (Absolute values of the real monotonic time are not readily observable or distinguishable from Rust, nor can a fixed Instant be constructed, so this is usually sufficient for a reproducible test.)

pub fn advance(&self, d: Duration)

Advance the simulated time by d

This advances both the Instant (monotonic time) and SystemTime (wallclock time) by the same amount.

Will wake sleeping SleepFutures, as appropriate.

Note that the tasks which were waiting on those now-expired SleepFutures will only actually execute when they are next polled. advance does not yield to the executor or poll any futures. The executor will (presumably) poll those woken tasks, when it regains control. But the order in which the tasks run will depend on its scheduling policy, and might be different to the order implied by the futures’ timeout values.

To simulate normal time advancement, wakeups, and task activations, use MockExecutor::advance_*().

pub fn jump_wallclock(&self, new_wallclock: SystemTime)

Warp the wallclock time

This has no effect on any sleeping futures. It only affects the return value from .wallclock().

pub fn time_until_next_timeout(&self) -> Option<Duration>

When will the next timeout occur?

Returns the duration until the next SleepFuture should wake up.

Advancing time by at least this amount will wake up that future, and any others with the same wakeup time.

Will never return Some(ZERO): any future that is supposed to wake up now (or earlier) has indeed already been woken, so it is no longer sleeping and isn’t included in the calculation.

Trait Implementations

impl Clone for SimpleMockTimeProvider

fn clone(&self) -> SimpleMockTimeProvider

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl CoarseTimeProvider for SimpleMockTimeProvider

fn now_coarse(&self) -> CoarseInstant

Return the CoarseTimeProvider’s view of the current instant.

impl Debug for SimpleMockTimeProvider

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

Formats the value using the given formatter.

impl Default for SimpleMockTimeProvider

Default makes a Provider which starts at whatever the current real time is

fn default() -> Self

Returns the “default value” for a type.

impl SleepProvider for SimpleMockTimeProvider

type SleepFuture = SleepFuture

A future returned by SleepProvider::sleep()

fn sleep(&self, d: Duration) -> SleepFuture

Return a future that will be ready after duration has elapsed.

fn now(&self) -> Instant

Return the SleepProvider’s view of the current instant.

fn wallclock(&self) -> SystemTime

Return the SleepProvider’s view of the current wall-clock time.

fn block_advance<T>(&self, _reason: T)

where T: Into<String>,

Signify that a test running under mock time shouldn’t advance time yet, with a given unique reason string. This is useful for making sure (mock) time doesn’t advance while things that might require some (real-world) time to complete do so, such as spawning a task on another thread.

fn release_advance<T>(&self, _reason: T)

where T: Into<String>,

Signify that the reason to withhold time advancing provided in a call to block_advance no longer exists, and it’s fine to move time forward if nothing else is blocking advances.

fn allow_one_advance(&self, _dur: Duration)

Allow a test running under mock time to advance time by the provided duration, even if the above block_advance API has been used.