Struct fuchsia_async::TestExecutor

pub struct TestExecutor { /* private fields */ }

A single-threaded executor for testing. Exposes additional APIs for manipulating executor state and validating behavior of executed tasks.

Implementations

impl TestExecutor

pub fn new() -> Self

Create a new executor for testing.

pub fn new_with_fake_time() -> Self

Create a new single-threaded executor running with fake time.

pub fn now(&self) -> Time

Return the current time according to the executor.

pub fn set_fake_time(&self, t: Time)

Set the fake time to a given value.

Panics

If the executor was not created with fake time

pub fn run_singlethreaded<F>(&mut self, main_future: F) -> F::Output

where F: Future,

Run a single future to completion on a single thread, also polling other active tasks.

pub fn run_until_stalled<F>(&mut self, main_future: &mut F) -> Poll<F::Output>

where F: Future + Unpin,

PollResult the future. If it is not ready, dispatch available packets and possibly try again. Timers will only fire if this executor uses fake time. Never blocks.

This function is for testing. DO NOT use this function in tests or applications that involve any interaction with other threads or processes, as those interactions may become stalled waiting for signals from “the outside world” which is beyond the knowledge of the executor.

Unpin: this function requires all futures to be Unpinable, so any !Unpin futures must first be pinned using the pin! macro.

pub fn wake_expired_timers(&mut self) -> bool

Wake all tasks waiting for expired timers, and return true if any task was woken.

This is intended for use in test code in conjunction with fake time.

pub fn wake_next_timer(&mut self) -> Option<Time>

Wake up the next task waiting for a timer, if any, and return the time for which the timer was scheduled.

This is intended for use in test code in conjunction with run_until_stalled. For example, here is how one could test that the Timer future fires after the given timeout:

let deadline = 5.seconds().after_now();
let mut future = Timer::<Never>::new(deadline);
assert_eq!(Poll::Pending, exec.run_until_stalled(&mut future));
assert_eq!(Some(deadline), exec.wake_next_timer());
assert_eq!(Poll::Ready(()), exec.run_until_stalled(&mut future));

pub fn next_timer() -> Option<Time>

Returns the deadline for the next timer due to expire.

pub async fn advance_to(time: Time)

Advances fake time to the specified time. This will only work if the executor is being run via TestExecutor::run_until_stalled and can only be called by one task at a time. This will make sure that repeating timers fire as expected.

Panics

Panics if the executor was not created with fake time, and for the same reasons poll_until_stalled can below.

pub async fn poll_until_stalled<T>( fut: impl Future<Output = T> + Unpin ) -> Poll<T>

Runs the future until it is ready or the executor is stalled. Returns the state of the future.

This will only work if the executor is being run via TestExecutor::run_until_stalled and can only be called by one task at a time.

This can be used in tests to assert that a future should be pending:

assert!(
    TestExecutor::poll_until_stalled(my_fut).await.is_pending(),
    "my_fut should not be ready!"
);

If you just want to know when the executor is stalled, you can do:

let _: Poll<()> = TestExecutor::poll_until_stalled(future::pending::<()>()).await;

Panics

Panics if another task is currently trying to use run_until_stalled, or the executor is not using TestExecutor::run_until_stalled.