Struct 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.

TODO(https://fxbug.dev/375631801): This is lack of BootInstant support.

Implementations

impl TestExecutor

pub fn new() -> Self

Create a new executor for testing.

pub fn port(&self) -> &Port

Get a reference to the Fuchsia zx::Port being used to listen for events.

pub fn new_with_fake_time() -> Self

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

pub fn now(&self) -> MonotonicInstant

Return the current time according to the executor.

pub fn boot_now(&self) -> BootInstant

Return the current time on the boot timeline, according to the executor.

pub fn set_fake_time(&self, t: MonotonicInstant)

Set the fake time to a given value.

Panics

If the executor was not created with fake time.

pub fn set_fake_boot_to_mono_offset(&self, d: BootDuration)

Set the offset between the reading of the monotonic and the boot clocks.

This is useful to test the situations in which the boot and monotonic offsets diverge. In realistic scenarios, the offset can only grow, and testers should keep that in view when setting duration.

Panics

If the executor was not created with fake time.

pub fn global_scope(&self) -> &ScopeHandle

Get the global scope of the executor.

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,

Poll 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.

The wake will have effect on both the monotonic and the boot timers.

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

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 = zx::MonotonicDuration::from_seconds(5).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 wake_next_boot_timer(&mut self) -> Option<BootInstant>

Similar to [wake_next_timer], but operates on the timers on the boot timeline.

pub fn next_timer() -> Option<MonotonicInstant>

Returns the deadline for the next timer due to expire.

pub fn next_boot_timer() -> Option<BootInstant>

Returns the deadline for the next boot timeline timer due to expire.

pub async fn advance_to(time: MonotonicInstant)

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.