blob: 489d5ff4f47d744ec3454df82ad0aa4cb6d588be [file]
// Copyright 2025 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//! Helpers for writing tests using drivers and dispatchers
use std::sync::{Arc, mpsc};
use fdf_core::dispatcher::{AutoReleaseDispatcher, CurrentDispatcher};
use libasync_dispatcher::{AsAsyncDispatcherRef, AsyncDispatcher, OnDispatcher};
use super::*;
/// The value pointed to by the drivers created by these helpers.
const TEST_DRIVER_VALUE: u32 = 0x1337;
/// Runs the given closure under the a new root driver dispatcher. Use [`fdf::CurrentDispatcher`]
/// to reference the dispatcher if needed.
pub fn run_in_driver<T: Send + 'static>(name: &str, p: impl FnOnce() -> T + Send + 'static) -> T {
run_in_driver_raw(name, true, false, |tx| tx.send(p()).unwrap())
}
/// Runs the given closure under a new root driver dispatcher, with some additional options.
/// Use [`fdf::CurrentDispatcher`] to reference the dispatcher if needed.
pub fn run_in_driver_etc<T: Send + 'static>(
name: &str,
allow_thread_blocking: bool,
unsynchronized: bool,
p: impl FnOnce() -> T + Send + 'static,
) -> T {
run_in_driver_raw(name, allow_thread_blocking, unsynchronized, |tx| tx.send(p()).unwrap())
}
/// Runs the given future to completion under the a new root driver dispatcher. Use
/// [`fdf::CurrentDispatcher`] to reference the dispatcher if needed.
pub fn spawn_in_driver<T: Send + 'static>(
name: &str,
p: impl Future<Output = T> + Send + 'static,
) -> T {
run_in_driver_raw(name, true, false, |tx| {
CurrentDispatcher.spawn(async move { tx.send(p.await).unwrap() });
})
}
/// Runs the given future to completion under a new root driver dispatcher, with some additional
/// options. Use [`fdf::CurrentDispatcher`] to reference the dispatcher if needed.
pub fn spawn_in_driver_etc<T: Send + 'static>(
name: &str,
allow_thread_blocking: bool,
unsynchronized: bool,
p: impl Future<Output = T> + Send + 'static,
) -> T {
run_in_driver_raw(name, allow_thread_blocking, unsynchronized, |tx| {
CurrentDispatcher.spawn(async move { tx.send(p.await).unwrap() });
})
}
/// Creates a new driver with a new root dispatcher, and runs the given closure on the current
/// thread with them.
///
/// Unlike [`run_in_driver`], the closure is not run on the dispatcher, so it may block waiting on
/// work done by the dispatcher.
///
/// `configure` may be used to set additional options on the dispatcher before it is created. It is
/// also given the [`Environment`], so that it can e.g. set scheduler role options first. It must not
/// set a shutdown observer.
///
/// `p` is given the driver, which may be used to e.g. suspend and resume its dispatchers, and the
/// root dispatcher. Once `p` returns, all dispatchers owned by the driver are shut down, and this
/// blocks until the driver runtime has finished destroying them.
///
/// # Panics
///
/// This must not be called from a thread managed by the driver runtime.
pub fn with_driver_dispatcher<T>(
name: &str,
configure: impl FnOnce(&Environment, DispatcherBuilder) -> DispatcherBuilder,
p: impl FnOnce(&Driver<u32>, AsyncDispatcher) -> T,
) -> T {
with_test_driver(name, configure, |driver, dispatcher| {
p(driver, dispatcher.as_async_dispatcher())
})
}
fn run_in_driver_raw<T: Send + 'static>(
name: &str,
allow_thread_blocking: bool,
unsynchronized: bool,
p: impl FnOnce(mpsc::Sender<T>) + Send + 'static,
) -> T {
with_test_driver(
name,
|_env, dispatcher| {
let dispatcher =
if allow_thread_blocking { dispatcher.allow_thread_blocking() } else { dispatcher };
if unsynchronized { dispatcher.unsynchronized() } else { dispatcher }
},
|_driver, dispatcher| {
let (finished_tx, finished_rx) = mpsc::channel();
dispatcher
.post_task_sync(move |_| {
p(finished_tx);
})
.unwrap();
finished_rx.recv().unwrap()
},
)
}
/// Creates a new driver with a root dispatcher configured by `configure`, and calls `p` with them.
/// Once `p` returns, shuts down the driver and waits for the runtime to finish destroying all of
/// its dispatchers.
fn with_test_driver<T>(
name: &str,
configure: impl FnOnce(&Environment, DispatcherBuilder) -> DispatcherBuilder,
p: impl FnOnce(&Driver<u32>, &AutoReleaseDispatcher) -> T,
) -> T {
let env = Arc::new(Environment::start(0).unwrap());
let env_clone = env.clone();
let driver_value: u32 = TEST_DRIVER_VALUE;
let driver_value_ptr = &driver_value as *const u32;
let driver = env.new_driver(driver_value_ptr);
let dispatcher =
configure(&env, DispatcherBuilder::new().name(name)).shutdown_observer(move |dispatcher| {
// We verify that the dispatcher has no tasks left queued in it,
// just because this is testing code.
assert!(!env_clone.dispatcher_has_queued_tasks(dispatcher.as_dispatcher_ref()));
});
let dispatcher = driver.new_dispatcher(dispatcher).unwrap().release();
let res = p(&driver, &dispatcher);
let (shutdown_tx, shutdown_rx) = mpsc::channel();
driver.shutdown(move |driver| {
// SAFETY: driver lives on the stack, it's safe to dereference it.
assert!(unsafe { *driver.0 } == TEST_DRIVER_VALUE);
shutdown_tx.send(()).unwrap();
});
shutdown_rx.recv().unwrap();
// The driver shutdown observer is called once every dispatcher shutdown observer for the
// driver has returned, but the runtime may still be in the middle of destroying the
// dispatchers. Wait for that to finish, so that the test (and with it, the test process)
// doesn't finish while the runtime is still tearing them down.
env.destroy_all_dispatchers();
res
}