Struct tor_rtmock::MockRuntime

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.

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

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

See SimpleMockTimeProvider::jump_wallclock()

pub fn jump_wallclock(&self, new_wallclock: SystemTime)

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 BlockOn for MockRuntime

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

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

impl Clone for MockRuntime

fn clone(&self) -> MockRuntime

Returns a copy of the value. Read more

1.0.0 · source§

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

Performs copy-assignment from source. Read more

impl Debug for MockRuntime

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

Formats the value using the given formatter. Read more

impl Default for MockRuntime

fn default() -> MockRuntime

Returns the “default value” for a type. Read more

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. Read more

fn wallclock(&self) -> SystemTime

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

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. Read more

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. Read more

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. Read more

impl Spawn for MockRuntime

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

Spawns a future that will be run to completion. Read more

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

Determines whether the executor is able to spawn new tasks. Read more

impl TcpProvider for MockRuntime

type TcpStream = <MockNetProvider as TcpProvider>::TcpStream

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

type TcpListener = <MockNetProvider as TcpProvider>::TcpListener

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

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

Launch a TCP connection to a given socket address. Read more

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

Open a TCP listener on a given socket address.

impl TlsProvider<<MockNetProvider as TcpProvider>::TcpStream> for MockRuntime

type Connector = <MockNetProvider as TlsProvider<<MockNetProvider as TcpProvider>::TcpStream>>::Connector

The Connector object that this provider can return.

type TlsStream = <MockNetProvider as TlsProvider<<MockNetProvider as TcpProvider>::TcpStream>>::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.

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

Auto Trait Implementations§

impl UnwindSafe for MockRuntime

Blanket Implementations§

impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T
where T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T
where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into for T
where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl<T> SleepProviderExt for T
where T: SleepProvider,

fn timeout<F>( &self, duration: Duration, future: F ) -> Timeout<F, Self::SleepFuture>
where F: Future,

Wrap a Future with a timeout. Read more

fn sleep_until_wallclock( &self, when: SystemTime ) -> SleepUntilWallclock<'_, Self>

Pause until the wall-clock is at when or later, trying to recover from clock jumps. Read more

impl<Sp> SpawnExt for Sp
where Sp: Spawn + ?Sized,

fn spawn<Fut>(&self, future: Fut) -> Result<(), SpawnError>
where Fut: Future<Output = ()> + Send + 'static,

Available on crate feature alloc only.

Spawns a task that polls the given future with output () to completion. Read more

fn spawn_with_handle<Fut>( &self, future: Fut ) -> Result<RemoteHandle<<Fut as Future>::Output>, SpawnError>
where Fut: Future + Send + 'static, <Fut as Future>::Output: Send,

Available on crate features channel and std only.

Spawns a task that polls the given future to completion and returns a future that resolves to the spawned future’s output. Read more

impl<T> ToOwned for T
where T: Clone,

type Owned = T

The resulting type after obtaining ownership.

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T, U> TryFrom for T
where U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

impl<T, U> TryInto for T
where U: TryFrom<T>,

type Error = >::Error

The type returned in the event of a conversion error.

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more