Struct MockRuntime

pub struct MockRuntime {
    task: MockExecutor,
    sleep: SimpleMockTimeProvider,
    net: MockNetProvider,
}

Completely mock runtime, with simulated time

Suitable for test cases that wish to completely control the environment experienced by the code under test.

Useful properties

The execution order is deterministic. Time will advance only in a controlled fashion. Typically, the main task in a test will call advance_until_stalled.

Reliable sequencing techniques which can be used in tests include: sleeping for carefully chosen durations; interlocking via intertask channels; or, sequenced control of requests to the code under test.

Restrictions

The test case must advance the mock time explicitly as desired, typically by calling one of the MockRuntime::advance_* methods.

Tests that use this runtime must not interact with the outside world; everything must go through this runtime (and its pieces).

There is no mocking of filesystem access; the MockRuntime’s time will disagree with SystemTime’s obtained from (for example) std::fs::Metadata.

Allowed

• Inter-future communication facilities from futures or other runtime-agnostic crates.

• Fast synchronous operations that will complete “immediately” or “quickly”. E.g.: filesystem calls.

• std::sync::Mutex (assuming the use is deadlock-free in a single-threaded executor, as it should be in all of Arti).

• Slower operations that are run synchronously (without futures await) provided their completion doesn’t depend on any of the futures we’re running. (These kind of operations are often discouraged in async contexts, because they block the async runtime or its worker threads. But they are often OK in tests.)

• All facilities provided by this MockExecutor and its trait impls.

Not allowed

• Direct access to the real-world clock (SystemTime::now, Instant::now), including direct use of coarsetime. Instead, use SleepProvider and CoarseTimeProvider methods on the runtime. Exception: CPU use measurements.

• Anything that spawns threads and then communicates with those threads using async Rust facilities (futures).

• Async sockets, or async use of other kernel-based IPC or network mechanisms.

• Anything provided by a Rust runtime/executor project (eg anything from Tokio), unless it is definitively established that it’s runtime-agnostic.

Fields

task: MockExecutor

Tasks

sleep: SimpleMockTimeProvider

Time provider

net: MockNetProvider

Net provider

Implementations

impl MockRuntime

pub fn mock_task(&self) -> &MockExecutor

Method borrowing MockRuntime::task field. Tasks

pub fn mock_sleep(&self) -> &SimpleMockTimeProvider

Method borrowing MockRuntime::sleep field. Time provider

pub fn mock_net(&self) -> &MockNetProvider

Method borrowing MockRuntime::net field. Net provider

impl MockRuntime

pub fn new() -> Self

Create a new MockRuntime with default parameters

pub fn builder() -> MockRuntimeBuilder

Return a builder, for creating a MockRuntime with some parameters manually configured

pub fn test_with_various<TC, FUT>(test_case: TC)

where TC: FnMut(MockRuntime) -> FUT, FUT: Future<Output = ()>,

Run a test case with a variety of runtime parameters, to try to find bugs

test_case is an async closure which receives a MockRuntime. It will be run with a number of differently configured executors.

Each run will be preceded by an eprintln! showing the runtime configuration.

Variations

The only variation currently implemented is this:

Both FIFO and LIFO scheduling policies are tested, in the hope that this will help discover ordering-dependent bugs.

pub fn try_test_with_various<TC, FUT, E>(test_case: TC) -> Result<(), E>

where TC: FnMut(MockRuntime) -> FUT, FUT: Future<Output = Result<(), E>>,

Run a faillible test case with a variety of runtime parameters, to try to find bugs

test_case is an async closure which receives a MockRuntime. It will be run with a number of differently configured executors.

This function accepts a fallible closure, and returns the first Err to the caller.

See test_with_various() for more details.

pub fn spawn_identified( &self, desc: impl Display, fut: impl Future<Output = ()> + Send + 'static, ) -> impl Debug + Clone + Send + 'static

Spawn a task and return something to identify it

See MockExecutor::spawn_identified()

pub fn spawn_join<T: Debug + Send + 'static>( &self, desc: impl Display, fut: impl Future<Output = T> + Send + 'static, ) -> impl Future<Output = T>

Spawn a task and return its output for further usage

See MockExecutor::spawn_join()

pub async fn advance_until_stalled(&self)

Run tasks and advance time, until every task except this one is waiting

On return the other tasks won’t be waiting on timeouts, since time will be advanced as needed.

Therefore the other tasks (if any) will be waiting for something that won’t happen by itself, such as a provocation via their APIs from this task.

Panics

See progress_until_stalled

pub async fn progress_until_stalled(&self)

Run tasks in the current executor until every task except this one is waiting

Calls MockExecutor::progress_until_stalled().

Restriction - no automatic time advance

The mocked time will not be automatically advanced.

Usually (and especially if the tasks under test are waiting for timeouts or periodic events) you must use advance_by() or advance_until() to ensure the simulated time progresses as required.

Panics

Might malfunction or panic if more than one such call is running at once.

(Ie, you must .await or drop the returned Future before calling this method again.)

Must be called and awaited within a future being run by self.

pub async fn advance_until(&self, limit: Instant) -> Option<Duration>

Run tasks and advance time up to at most limit

Will return when all other tasks are either:

• Waiting on a timeout that will fire strictly after limit, (return value is the time until the earliest such)
• Waiting for something else that won’t happen by itself. (return value is None)

Like advance_until_stalled but stops when the mock time reaches limit.

Panics

Panics if the time somehow advances beyond limit. (This function won’t do that, but maybe it was beyond limit on entry, or another task advanced the clock.)

And, see progress_until_stalled

async fn advance_inner<B>( &self, body: impl FnMut() -> ControlFlow<B, Duration>, ) -> B

Advance time, firing events and other tasks - internal implementation

Common code for advance_*.

body will called after progress_until_stalled. It should examine the simulated time, and the next timeout, and decide what to do - returning Break to break the loop, or Continue giving the Duration by which to advance time and go round again.

pub async fn advance_by(&self, dur: Duration) -> Option<Duration>

Advances time by dur, firing time events and other tasks in order

Prefer this to SimpleMockTimeProvider::advance(); it works more faithfully.

Specifically, it advances time in successive stages, so that timeouts occur sequentially, in the right order.

Panics

Can panic if the mock time is advanced by other tasks.

And, see progress_until_stalled

pub fn jump_wallclock(&self, new_wallclock: SystemTime)

See SimpleMockTimeProvider::jump_wallclock()

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

Return the amount of virtual time until the next timeout should elapse.

If there are no more timeouts, return None.

If the next timeout should elapse right now, return Some(0). However, if other tasks are proceeding, typically in that situation those other tasks will wake, so a Some(0) return won’t be visible. In test cases, detect immediate timeouts by detecting what your task does after the timeout occurs.

Likewise whether this function returns None or Some(...) can depend on whether tasks have actually yet polled various futures. The answer should be correct after progress_until_stalled.

Trait Implementations

impl Blocking for MockRuntime

type ThreadHandle<T: Send + 'static> = <MockExecutor as Blocking>::ThreadHandle<T>

Future from spawn_blocking

fn spawn_blocking<F, T>( &self, f: F, ) -> <MockExecutor as Blocking>::ThreadHandle<T>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawn a thread for blocking IO or CPU-bound work.

fn reenter_block_on<F>(&self, future: F) -> F::Output

where F: Future, F::Output: Send + 'static,

Block on a future, from within Blocking::spawn_blocking

fn blocking_io<F, T>(&self, f: F) -> impl Future<Output = T>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Perform some blocking IO from an async future

impl Clone for MockRuntime

fn clone(&self) -> MockRuntime

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl CoarseTimeProvider for MockRuntime

fn now_coarse(&self) -> CoarseInstant

Return the CoarseTimeProvider’s view of the current instant.

impl Debug for MockRuntime

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

Formats the value using the given formatter.

impl Default for MockRuntime

fn default() -> MockRuntime

Returns the “default value” for a type.

impl NetStreamProvider<SocketAddr> for MockRuntime

type Stream = FakeStream

The type for the connections returned by Self::connect().

type Listener = FakeListener<SocketAddr>

The type for the listeners returned by Self::listen().

fn connect<'life0, 'life1, 'async_trait>( &'life0 self, _addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = IoResult<Self::Stream>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Launch a connection connection to a given socket address.

fn listen<'life0, 'life1, 'async_trait>( &'life0 self, _addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = IoResult<Self::Listener>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Open a listener on a given socket address.

impl NetStreamProvider for MockRuntime

type Stream = <MockNetProvider as NetStreamProvider>::Stream

The type for the connections returned by Self::connect().

type Listener = <MockNetProvider as NetStreamProvider>::Listener

The type for the listeners returned by Self::listen().

fn connect<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = IoResult<Self::Stream>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Launch a connection connection to a given socket address.

fn listen<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = IoResult<Self::Listener>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Open a listener on a given socket address.

impl SleepProvider for MockRuntime

type SleepFuture = <SimpleMockTimeProvider as SleepProvider>::SleepFuture

A future returned by SleepProvider::sleep()

fn sleep(&self, dur: Duration) -> Self::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: Into<String>>(&self, reason: T)

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: Into<String>>(&self, reason: T)

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.

impl Spawn for MockRuntime

fn spawn_obj(&self, future: FutureObj<'static, ()>) -> Result<(), SpawnError>

Spawns a future that will be run to completion.

fn status(&self) -> Result<(), SpawnError>

Determines whether the executor is able to spawn new tasks.

impl TlsProvider<<MockNetProvider as NetStreamProvider>::Stream> for MockRuntime

type Connector = <MockNetProvider as TlsProvider<<MockNetProvider as NetStreamProvider>::Stream>>::Connector

The Connector object that this provider can return.

type TlsStream = <MockNetProvider as TlsProvider<<MockNetProvider as NetStreamProvider>::Stream>>::TlsStream

The type of the stream returned by that connector.

fn tls_connector(&self) -> Self::Connector

Return a TLS connector for use with this runtime.

fn supports_keying_material_export(&self) -> bool

Return true iff the keying material exporters (RFC 5705) is supported.

impl ToplevelBlockOn for MockRuntime

fn block_on<F: Future>(&self, future: F) -> F::Output

Run future until it is ready, and return its output.

impl UdpProvider for MockRuntime

type UdpSocket = <MockNetProvider as UdpProvider>::UdpSocket

The type of Udp Socket returned by Self::bind()

fn bind<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = IoResult<Self::UdpSocket>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Bind a local port to send and receive packets from