Struct tor_rtmock::task::MockExecutor

pub struct MockExecutor { /* private fields */ }

Executor for running tests with mocked environment

For test cases which don’t actually wait for anything in the real world.

This is the executor. It implements Spawn and BlockOn

It will usually be used as part of a MockRuntime.

Restricted environment

Tests run with this executor must not attempt to block on anything “outside”: every future that anything awaits must (eventually) be woken directly by some other task in the same test case.

(By directly we mean that the Waker::wake call is made by that waking future, before that future itself awaits anything.)

Panics

This executor will malfunction or panic if reentered.

Implementations

impl MockExecutor

pub fn new() -> Self

Make a MockExecutor with default parameters

pub fn with_scheduling(scheduling: SchedulingPolicy) -> Self

Make a MockExecutor with a specific SchedulingPolicy

impl MockExecutor

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

desc should Display as some kind of short string (ideally without spaces) and will be used in the Debug impl and trace log messages from MockExecutor.

The returned value is an opaque task identifier which is very cheap to clone and which can be used by the caller in debug logging, if it’s desired to correlate with the debug output from MockExecutor. Most callers will want to ignore it.

This method is infalliable. (The MockExecutor cannot be shut down.)

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

desc should Display as some kind of short string (ideally without spaces) and will be used in the Debug impl and trace log messages from MockExecutor.

impl MockExecutor

pub fn progress_until_stalled(&self) -> impl Future<Output = ()>

Run tasks in the current executor until every other task is waiting

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.

impl MockExecutor

pub fn n_tasks(&self) -> usize

Return the number of tasks running in this executor

One possible use is for a test case to check that task(s) that ought to have exited, have indeed done so.

In the usual case, the answer will be at least 1, because it counts the future passed to block_on (perhaps via MockRuntime::test_with_various).

impl MockExecutor

pub fn debug_dump(&self)

Dump the executor’s state including backtraces of waiting tasks, to stderr

This is considerably more extensive than simply MockExecutor as Debug.

(This is a convenience method, which wraps MockExecutor::as_debug_dump().

Backtrace salience (possible spurious traces)

Summary

The technique used to capture backtraces when futures sleep is not 100% exact. It will usually show all the actual sleeping sites, but it might also show other backtraces which were part of the implementation of some complex relevant future.

Details

When a future’s implementation wants to sleep, it needs to record the Waker (from the Context) so that the “other end” can call .wake() on it later, when the future should be woken.

Since Context.waker() gives &Waker, borrowed from the Context, the future must clone the Waker, and it must do so in within the poll() call.

A future which is waiting in a select! will typically show multiple traces, one for each branch. But, if a future sleeps on one thing, and then when polled again later, sleeps on something different, without waking up in between, both backtrace locations will be shown. And, a complicated future contraption might clone the Waker more times. So not every backtrace will necessarily be informative.

Panics

Panics on write errors.

pub fn as_debug_dump(&self) -> DebugDump<'_>

Dump the executor’s state including backtraces of waiting tasks

This is considerably more extensive than simply MockExecutor as Debug.

Returns an object for formatting with Debug. To simply print the dump to stderr (eg in a test), use .debug_dump().

Backtrace salience (possible spurious traces) - see .debug_dump().

Trait Implementations

impl BlockOn for MockExecutor

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

where F: Future,

Run fut to completion, synchronously

Panics

Might malfunction or panic if:

• The provided future doesn’t complete (without externally blocking), but instead waits for something.

• The MockExecutor is reentered. (Eg, block_on is reentered.)

impl Clone for MockExecutor

fn clone(&self) -> MockExecutor

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MockExecutor

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

Formats the value using the given formatter.

impl Default for MockExecutor

fn default() -> MockExecutor

Returns the “default value” for a type.

impl Spawn for MockExecutor

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.