blob: 29e13b0929b2d8d9c356405d73081b1b5a53542b [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.
//! Safe bindings for driver runtime environment.
#![deny(missing_docs)]
use fdf_sys::*;
use zx::sys::zx_duration_mono_t;
use core::ffi;
use core::marker::PhantomData;
use core::ptr::{NonNull, null_mut};
use zx::Status;
use fdf_core::dispatcher::{Dispatcher, DispatcherBuilder, DriverDispatcherRef};
use fdf_core::shutdown_observer::ShutdownObserver;
pub mod test;
const FDF_DISPATCHER_STATE_RUNNING: fdf_dispatcher_state_t = 0;
const FDF_DISPATCHER_STATE_SHUTTING_DOWN: fdf_dispatcher_state_t = 1;
const FDF_DISPATCHER_STATE_SHUTDOWN: fdf_dispatcher_state_t = 2;
const FDF_DISPATCHER_STATE_DESTROYED: fdf_dispatcher_state_t = 3;
/// Create the dispatcher as configured by this object. This must be called from a
/// thread managed by the driver runtime. The dispatcher returned is owned by the caller,
/// and will initiate asynchronous shutdown when the object is dropped unless
/// [`Dispatcher::release`] is called on it to convert it into an unowned [`DispatcherRef`].
fn create_with_driver<'a>(
dispatcher: DispatcherBuilder,
driver: DriverRefTypeErased<'a>,
) -> Result<Dispatcher, Status> {
let mut out_dispatcher = null_mut();
let owner = driver.0;
let options = dispatcher.options;
let name = dispatcher.name.as_ptr() as *mut ffi::c_char;
let name_len = dispatcher.name.len();
let scheduler_role = dispatcher.scheduler_role.as_ptr() as *mut ffi::c_char;
let scheduler_role_len = dispatcher.scheduler_role.len();
let observer =
ShutdownObserver::new(dispatcher.shutdown_observer.unwrap_or_else(|| Box::new(|_| {})))
.into_ptr();
// SAFETY: all arguments point to memory that will be available for the duration
// of the call, except `observer`, which will be available until it is unallocated
// by the dispatcher exit handler.
Status::ok(unsafe {
fdf_env_dispatcher_create_with_owner(
owner,
options,
name,
name_len,
scheduler_role,
scheduler_role_len,
observer,
&mut out_dispatcher,
)
})?;
// SAFETY: `out_dispatcher` is valid by construction if `fdf_dispatcher_create` returns
// ZX_OK.
Ok(unsafe { Dispatcher::from_raw(NonNull::new_unchecked(out_dispatcher)) })
}
/// A marker trait for a function that can be used as a driver shutdown observer with
/// [`Driver::shutdown`].
pub trait DriverShutdownObserverFn<T: 'static>:
FnOnce(DriverRef<'static, T>) + Send + Sync + 'static
{
}
impl<T, U: 'static> DriverShutdownObserverFn<U> for T where
T: FnOnce(DriverRef<'static, U>) + Send + Sync + 'static
{
}
/// A shutdown observer for [`fdf_dispatcher_create`] that can call any kind of callback instead of
/// just a C-compatible function when a dispatcher is shutdown.
///
/// # Safety
///
/// This object relies on a specific layout to allow it to be cast between a
/// `*mut fdf_dispatcher_shutdown_observer` and a `*mut ShutdownObserver`. To that end,
/// it is important that this struct stay both `#[repr(C)]` and that `observer` be its first member.
#[repr(C)]
struct DriverShutdownObserver<T: 'static> {
observer: fdf_env_driver_shutdown_observer,
shutdown_fn: Box<dyn DriverShutdownObserverFn<T>>,
driver: Driver<T>,
}
impl<T: 'static> DriverShutdownObserver<T> {
/// Creates a new [`ShutdownObserver`] with `f` as the callback to run when a dispatcher
/// finishes shutting down.
fn new<F: DriverShutdownObserverFn<T>>(driver: Driver<T>, f: F) -> Self {
let shutdown_fn = Box::new(f);
Self {
observer: fdf_env_driver_shutdown_observer { handler: Some(Self::handler) },
shutdown_fn,
driver,
}
}
/// Begins the driver shutdown procedure.
/// Turns this object into a stable pointer suitable for passing to
/// [`fdf_env_shutdown_dispatchers_async`] by wrapping it in a [`Box`] and leaking it
/// to be reconstituded by [`Self::handler`] when the dispatcher is shut down.
fn begin(self) -> Result<(), Status> {
let driver = self.driver.inner.as_ptr() as *const _;
// Note: this relies on the assumption that `self.observer` is at the beginning of the
// struct.
let this = Box::into_raw(Box::new(self)) as *mut _;
// SAFETY: driver is owned by the driver framework and will be kept alive until the handler
// callback is triggered
if let Err(e) = Status::ok(unsafe { fdf_env_shutdown_dispatchers_async(driver, this) }) {
// SAFETY: The framework didn't actually take ownership of the object if the call
// fails, so we can recover it to avoid leaking.
let _ = unsafe { Box::from_raw(this as *mut DriverShutdownObserver<T>) };
return Err(e);
}
Ok(())
}
/// The callback that is registered with the driver that will be called when the driver
/// is shut down.
///
/// # Safety
///
/// This function should only ever be called by the driver runtime at dispatcher shutdown
/// time, must only ever be called once for any given [`ShutdownObserver`] object, and
/// that [`ShutdownObserver`] object must have previously been made into a pointer by
/// [`Self::into_ptr`].
unsafe extern "C" fn handler(
driver: *const ffi::c_void,
observer: *mut fdf_env_driver_shutdown_observer_t,
) {
// SAFETY: The driver framework promises to only call this function once, so we can
// safely take ownership of the [`Box`] and deallocate it when this function ends.
let observer = unsafe { Box::from_raw(observer as *mut DriverShutdownObserver<T>) };
(observer.shutdown_fn)(DriverRef(driver as *const T, PhantomData));
}
}
/// An owned handle to a Driver instance that can be used to create initial dispatchers.
#[derive(Debug)]
pub struct Driver<T> {
pub(crate) inner: NonNull<T>,
shutdown_triggered: bool,
}
/// An unowned handle to the driver that is returned through certain environment APIs like
/// |get_driver_on_thread_koid|.
pub struct UnownedDriver {
inner: *const ffi::c_void,
}
/// SAFETY: This inner pointer is movable across threads.
unsafe impl<T: Send> Send for Driver<T> {}
impl<T: 'static> Driver<T> {
/// Constructs a dispatcher from the given builder on this driver. Note that this dispatcher
/// cannot outlive the driver and is only capable of being stopped by shutting down the driver.
/// It is meant to be created to serve as the initial or default dispatcher for a driver.
///
/// The caller should make sure that the dispatcher is released so the driver runtime will
/// manage shutting it down, but that may be done differently in test contexts so it does not
/// force it.
pub fn new_dispatcher(&self, dispatcher: DispatcherBuilder) -> Result<Dispatcher, Status> {
create_with_driver(dispatcher, self.as_ref_type_erased())
}
/// Run a closure in the context of a driver.
pub fn enter<R>(&mut self, f: impl FnOnce() -> R) -> R {
unsafe { fdf_env_register_driver_entry(self.inner.as_ptr() as *const _) };
let res = f();
unsafe { fdf_env_register_driver_exit() };
res
}
/// Adds an allowed scheduler role to the driver
pub fn add_allowed_scheduler_role(&self, scheduler_role: &str) {
let driver_ptr = self.inner.as_ptr() as *const _;
let scheduler_role_ptr = scheduler_role.as_ptr() as *mut ffi::c_char;
let scheduler_role_len = scheduler_role.len();
unsafe {
fdf_env_add_allowed_scheduler_role_for_driver(
driver_ptr,
scheduler_role_ptr,
scheduler_role_len,
)
};
}
/// Registers a callback which is triggered whenever the runtime needs to be resumed.
/// Returns a registration handle that unregisters and frees the requester when dropped.
pub fn register_resume_requester(
&self,
requester: ResumeRequester,
) -> ResumeRequesterRegistration {
let driver_ptr = self.inner.as_ptr() as *const _;
let requester_ptr = requester.into_ptr();
// SAFETY: requester_ptr is used by the driver runtime as a callback function.
// The driver runtime does not manage this object's lifetime. driver_ptr is not modified
// by the runtime.
unsafe {
fdf_sys::fdf_env_register_resume_requester(driver_ptr, requester_ptr);
}
ResumeRequesterRegistration { driver_ptr, requester_ptr }
}
/// Asynchronously suspends the dispatchers owned by the driver.
pub fn driver_suspend(&self, completer: SuspendCompleter) {
unsafe {
fdf_sys::fdf_env_driver_suspend(self.inner.as_ptr() as *const _, completer.into_ptr());
}
}
/// Resumes the dispatchers owned by the driver.
pub fn driver_resume(&self) {
unsafe {
fdf_sys::fdf_env_driver_resume(self.inner.as_ptr() as *const _);
}
}
/// Asynchronously shuts down all dispatchers owned by |driver|.
/// |f| will be called once shutdown completes. This is guaranteed to be
/// after all the dispatcher's shutdown observers have been called, and will be running
/// on the thread of the final dispatcher which has been shutdown.
pub fn shutdown<F: DriverShutdownObserverFn<T>>(mut self, f: F) {
self.shutdown_triggered = true;
// It should be impossible for this to fail as we ensure we are the only caller of this
// API, so it cannot be triggered twice nor before the driver has been registered with the
// framework.
DriverShutdownObserver::new(self, f)
.begin()
.expect("Unexpectedly failed start shutdown procedure")
}
/// Create a reference to a driver without ownership. The returned reference lacks the ability
/// to perform most actions available to the owner of the driver, therefore it doesn't need to
/// have it's lifetime tracked closely.
fn as_ref_type_erased<'a>(&'a self) -> DriverRefTypeErased<'a> {
DriverRefTypeErased(self.inner.as_ptr() as *const _, PhantomData)
}
/// Releases ownership of this driver instance, allowing it to be shut down when the runtime
/// shuts down.
pub fn release(self) -> DriverRef<'static, T> {
DriverRef(self.inner.as_ptr() as *const _, PhantomData)
}
}
impl<T> Drop for Driver<T> {
fn drop(&mut self) {
assert!(self.shutdown_triggered, "Cannot drop driver, must call shutdown method instead");
}
}
impl<T> PartialEq<UnownedDriver> for Driver<T> {
fn eq(&self, other: &UnownedDriver) -> bool {
self.inner.as_ptr() as *const _ == other.inner
}
}
// Note that inner type is not guaranteed to not be null.
#[derive(Clone, Copy, PartialEq)]
struct DriverRefTypeErased<'a>(*const ffi::c_void, PhantomData<&'a u32>);
impl Default for DriverRefTypeErased<'_> {
fn default() -> Self {
DriverRefTypeErased(std::ptr::null(), PhantomData)
}
}
/// A lifetime-bound reference to a driver handle.
pub struct DriverRef<'a, T>(pub *const T, PhantomData<&'a Driver<T>>);
/// A marker trait for a function type that can be used as a stall scanner.
pub trait StallScannerFn: Fn(zx_duration_mono_t) + Send + Sync + 'static {}
impl<T> StallScannerFn for T where T: Fn(zx_duration_mono_t) + Send + Sync + 'static {}
/// A stall scanner for [`fdf_env_register_stall_scanner`] that can call any kind of callback instead of
/// just a C-compatible function when a dispatcher is shutdown.
///
/// # Safety
///
/// This object relies on a specific layout to allow it to be cast between a
/// `*mut fdf_env_stall_scanner` and a `*mut StallScanner`. To that end,
/// it is important that this struct stay both `#[repr(C)]` and that `scanner` be its first member.
#[repr(C)]
#[doc(hidden)]
pub struct StallScanner {
scanner: fdf_env_stall_scanner,
begin_fn: Box<dyn StallScannerFn>,
}
impl StallScanner {
/// Creates a new [`StallScanner`] with `f` as the callback to run when a dispatcher
/// finishes shutting down.
pub fn new<F: StallScannerFn>(f: F) -> Self {
let begin_fn = Box::new(f);
Self { scanner: fdf_env_stall_scanner { handler: Some(Self::handler) }, begin_fn }
}
/// Turns this object into a stable pointer suitable for passing to
/// [`fdf_env_register_stall_scanner`] by wrapping it in a [`Box`] and leaking it to be reconstituded
/// by [`Self::handler`] when the scanner is triggered.
pub fn into_ptr(self) -> *mut fdf_env_stall_scanner {
// Note: this relies on the assumption that `self.scanner` is at the beginning of the
// struct.
Box::leak(Box::new(self)) as *mut _ as *mut _
}
/// The callback that is registered with the dispatcher that will be called when the stall
/// scanner should begin a scan.
///
/// # Safety
///
/// The [`StallScanner`] object must have previously been made into a pointer by
/// [`Self::into_ptr`].
unsafe extern "C" fn handler(
scanner: *mut fdf_env_stall_scanner,
duration: zx_duration_mono_t,
) {
let scanner = scanner as *mut StallScanner;
unsafe {
((*scanner).begin_fn)(duration);
}
}
}
/// A marker trait for a function type that can be used as a resume requester.
pub trait ResumeRequesterFn: Fn() -> Result<(), Status> + Send + Sync + 'static {}
impl<T> ResumeRequesterFn for T where T: Fn() -> Result<(), Status> + Send + Sync + 'static {}
/// A resume requester for [`fdf_env_register_resume_requester`] that can call any kind of callback.
///
/// # Safety
///
/// This object relies on a specific layout to allow it to be cast between a
/// `*mut fdf_env_resume_requester_t` and a `*mut ResumeRequester`. To that end,
/// it is important that this struct stay both `#[repr(C)]` and that `requester` be its first member.
#[repr(C)]
pub struct ResumeRequester {
/// The underlying C structure.
pub requester: fdf_env_resume_requester_t,
resume_fn: Box<dyn ResumeRequesterFn>,
}
impl ResumeRequester {
/// Creates a new [`ResumeRequester`] with `f` as the callback to run when the runtime needs to be resumed.
pub fn new<F: ResumeRequesterFn>(f: F) -> Self {
let resume_fn = Box::new(f);
Self { requester: fdf_env_resume_requester_t { handler: Some(Self::handler) }, resume_fn }
}
/// Turns this object into a stable pointer suitable for passing to
/// [`fdf_env_register_resume_requester`] by wrapping it in a [`Box`] and leaking it to be reconstituded
/// by [`Self::handler`] when the runtime needs to be resumed.
pub fn into_ptr(self) -> *mut fdf_env_resume_requester_t {
Box::leak(Box::new(self)) as *mut _ as *mut _
}
/// The callback that is registered with the dispatcher that will be called when the runtime
/// needs to be resumed.
///
/// # Safety
///
/// The [`ResumeRequester`] object must have previously been made into a pointer by
/// [`Self::into_ptr`].
unsafe extern "C" fn handler(requester: *mut fdf_env_resume_requester_t) -> i32 {
let requester = requester as *mut ResumeRequester;
unsafe {
match ((*requester).resume_fn)() {
Ok(()) => 0,
Err(e) => e.into_raw(),
}
}
}
}
/// A marker trait for a function type that can be used as a suspend completer.
pub trait SuspendCompleterFn: FnOnce() + Send + Sync + 'static {}
impl<T> SuspendCompleterFn for T where T: FnOnce() + Send + Sync + 'static {}
/// A suspend completer for [`fdf_env_driver_suspend`] that can call any kind of callback.
///
/// # Safety
///
/// This object relies on a specific layout to allow it to be cast between a
/// `*mut fdf_env_suspend_completer_t` and a `*mut SuspendCompleter`. To that end,
/// it is important that this struct stay both `#[repr(C)]` and that `completer` be its first member.
#[repr(C)]
pub struct SuspendCompleter {
completer: fdf_env_suspend_completer_t,
complete_fn: Box<dyn SuspendCompleterFn>,
}
impl SuspendCompleter {
/// Creates a new [`SuspendCompleter`] with `f` as the callback to run when the runtime finishes suspending.
pub fn new<F: SuspendCompleterFn>(f: F) -> Self {
let complete_fn = Box::new(f);
Self {
completer: fdf_env_suspend_completer_t { handler: Some(Self::handler) },
complete_fn,
}
}
/// Turns this object into a stable pointer suitable for passing to
/// [`fdf_env_driver_suspend`] by wrapping it in a [`Box`] and leaking it to be reconstituded
/// by [`Self::handler`] when the runtime finishes suspending.
pub fn into_ptr(self) -> *mut fdf_env_suspend_completer_t {
Box::leak(Box::new(self)) as *mut _ as *mut _
}
/// The callback that is registered with the dispatcher that will be called when the runtime
/// finishes suspending.
///
/// # Safety
///
/// The [`SuspendCompleter`] object must have previously been made into a pointer by
/// [`Self::into_ptr`].
unsafe extern "C" fn handler(completer: *mut fdf_env_suspend_completer_t) {
let completer = completer as *mut SuspendCompleter;
unsafe {
let completer = Box::from_raw(completer);
(completer.complete_fn)();
}
}
}
/// The driver runtime environment
pub struct Environment;
impl Environment {
/// Whether the environment should enforce scheduler roles. Used with [`Self::start`].
pub const ENFORCE_ALLOWED_SCHEDULER_ROLES: u32 = 1;
/// Whether the environment should dynamically spawn threads on-demand for sync call dispatchers.
/// Used with [`Self::start`].
pub const DYNAMIC_THREAD_SPAWNING: u32 = 2;
/// Start the driver runtime. This sets up the initial thread that the dispatchers run on.
pub fn start(options: u32) -> Result<Environment, Status> {
// SAFETY: calling fdf_env_start, which does not have any soundness
// concerns for rust code. It may be called multiple times without any problems.
Status::ok(unsafe { fdf_env_start(options) })?;
Ok(Self)
}
/// Creates a new driver. It is expected that the driver passed in is a leaked pointer which
/// will only be recovered by triggering the shutdown method on the driver.
///
/// # Panics
///
/// This method will panic if |driver| is not null.
pub fn new_driver<T>(&self, driver: *const T) -> Driver<T> {
// We cast to *mut because there is not equivlaent version of NonNull for *const T.
Driver {
inner: NonNull::new(driver as *mut _).expect("driver must not be null"),
shutdown_triggered: false,
}
}
// TODO: Consider tracking all drivers and providing a method to shutdown all outstanding
// drivers and block until they've all finished shutting down.
/// Returns whether the current thread is managed by the driver runtime or not.
fn current_thread_managed_by_driver_runtime() -> bool {
// Safety: Calling fdf_dispatcher_get_current_dispatcher from any thread is safe. Because
// we are not actually using the dispatcher, we don't need to worry about it's lifetime.
!unsafe { fdf_dispatcher_get_current_dispatcher().is_null() }
}
/// Resets the driver runtime to zero threads. This may only be called when there are no
/// existing dispatchers.
///
/// # Panics
///
/// This method should not be called from a thread managed by the driver runtime,
/// such as from tasks or ChannelRead callbacks.
pub fn reset(&self) {
assert!(
!Self::current_thread_managed_by_driver_runtime(),
"reset must be called from a thread not managed by the driver runtime"
);
// SAFETY: calling fdf_env_reset, which does not have any soundness
// concerns for rust code. It may be called multiple times without any problems.
unsafe { fdf_env_reset() };
}
/// Destroys all dispatchers in the process and blocks the current thread
/// until each runtime dispatcher in the process is observed to have been destroyed.
///
/// This should only be used called after all drivers have been shutdown.
///
/// # Panics
///
/// This method should not be called from a thread managed by the driver runtime,
/// such as from tasks or ChannelRead callbacks.
pub fn destroy_all_dispatchers(&self) {
assert!(
!Self::current_thread_managed_by_driver_runtime(),
"destroy_all_dispatchers must be called from a thread not managed by the driver runtime"
);
unsafe { fdf_env_destroy_all_dispatchers() };
}
/// Returns whether the dispatcher has any queued tasks.
pub fn dispatcher_has_queued_tasks(&self, dispatcher: DriverDispatcherRef<'_>) -> bool {
unsafe {
fdf_env_dispatcher_has_queued_tasks(fdf_core::dispatcher_ptr(&dispatcher).as_ptr())
}
}
/// Returns structured runtime diagnostic dumps for all dispatchers currently tracked by the
/// driver runtime environment.
pub fn dump_all_dispatchers(&self) -> Vec<DispatcherDumpEntry> {
struct DumpEntriesGuard {
ptr: *mut fdf_dispatcher_dump_entry_t,
count: usize,
}
impl Drop for DumpEntriesGuard {
fn drop(&mut self) {
if !self.ptr.is_null() {
// SAFETY: `self.ptr` and `self.count` were populated by a single call to
// `fdf_env_get_all_dispatchers_dump`, which allocated the entry array and its
// nested string/task buffers on the C++ heap and transferred exclusive
// ownership to the caller. `DumpEntriesGuard` is dropped only after all temporary
// slices and `CStr` borrows derived from `self.ptr` have gone out of scope, so
// no dangling references can exist and the allocation is freed at most once.
unsafe {
fdf_env_free_all_dispatchers_dump(self.ptr, self.count);
}
}
}
}
let mut raw_entries: *mut fdf_dispatcher_dump_entry_t = null_mut();
let mut count: usize = 0;
// SAFETY: `raw_entries` and `count` are valid, initialized, and properly aligned stack
// variables passed via exclusive mutable references (`&mut`). The C++ implementation of
// `fdf_env_get_all_dispatchers_dump` writes the newly allocated buffer pointer and element
// count into these out-parameters synchronously before returning and does not retain the
// addresses of `raw_entries` or `count`, preserving Rust's aliasing and lifetime rules.
unsafe {
fdf_env_get_all_dispatchers_dump(&mut raw_entries, &mut count);
}
let guard = DumpEntriesGuard { ptr: raw_entries, count };
if guard.ptr.is_null() || guard.count == 0 {
return Vec::new();
}
// SAFETY: We verified that `guard.ptr` is non-null and `guard.count > 0`. By the FFI
// contract of `fdf_env_get_all_dispatchers_dump`, `guard.ptr` points to a single
// contiguous heap allocation of `guard.count` initialized and properly aligned
// `fdf_dispatcher_dump_entry_t` values whose total byte size does not exceed `isize::MAX`.
// Exclusive ownership of the allocation was transferred to this function and is held by
// `guard` for the entire lifetime of `entries`, ensuring the memory is neither mutated nor
// deallocated while the immutable slice borrow is active.
let entries = unsafe { core::slice::from_raw_parts(guard.ptr, guard.count) };
let mut result = Vec::with_capacity(guard.count);
for entry in entries {
let name = if entry.name.is_null() {
String::new()
} else {
// SAFETY: `entry.name` was checked to be non-null. `fdf_env_get_all_dispatchers_dump`
// initializes `entry.name` via `CopyStringToHeap` (`malloc` + `memcpy` + NUL-terminator)
// from a valid string view, guaranteeing a valid, NUL-terminated sequence of bytes
// within a single allocation smaller than `isize::MAX`. The underlying buffer is
// exclusively owned by `guard` and is not mutated or freed until `guard` is dropped
// after this loop, and `.to_string_lossy()` immediately copies the bytes into an
// owned Rust `String`.
unsafe { ffi::CStr::from_ptr(entry.name) }.to_string_lossy().into_owned()
};
let scheduler_role = if entry.scheduler_role.is_null() {
String::new()
} else {
// SAFETY: `entry.scheduler_role` was checked to be non-null. By the FFI contract of
// `fdf_env_get_all_dispatchers_dump`, it points to a heap-allocated, NUL-terminated
// C string created via `CopyStringToHeap` (`malloc` + `memcpy` + NUL-terminator)
// with size less than `isize::MAX`. The memory is exclusively owned by `guard`,
// remains immutable for the duration of this borrow, and is copied into an owned
// `String` before `guard` is dropped.
unsafe { ffi::CStr::from_ptr(entry.scheduler_role) }.to_string_lossy().into_owned()
};
let destroy_context = if entry.destroy_context.is_null() {
String::new()
} else {
// SAFETY: `entry.destroy_context` was checked to be non-null. By the FFI contract of
// `fdf_env_get_all_dispatchers_dump`, it points to a heap-allocated, NUL-terminated
// C string created via `CopyStringToHeap` (`malloc` + `memcpy` + NUL-terminator)
// with size less than `isize::MAX`. The memory is exclusively owned by `guard`,
// remains immutable for the duration of this borrow, and is copied into an owned
// `String` before `guard` is dropped.
unsafe { ffi::CStr::from_ptr(entry.destroy_context) }.to_string_lossy().into_owned()
};
let state = match entry.state {
FDF_DISPATCHER_STATE_RUNNING => DispatcherState::Running,
FDF_DISPATCHER_STATE_SHUTTING_DOWN => DispatcherState::ShuttingDown,
FDF_DISPATCHER_STATE_SHUTDOWN => DispatcherState::Shutdown,
FDF_DISPATCHER_STATE_DESTROYED => DispatcherState::Destroyed,
_ => DispatcherState::Running,
};
let mut queued_tasks = Vec::with_capacity(entry.num_queued_tasks);
if !entry.queued_tasks.is_null() && entry.num_queued_tasks > 0 {
// SAFETY: We verified that `entry.queued_tasks` is non-null and
// `entry.num_queued_tasks > 0`. By the contract of `fdf_env_get_all_dispatchers_dump`,
// `entry.queued_tasks` points to a contiguous heap allocation of
// `entry.num_queued_tasks` initialized and properly aligned `fdf_task_debug_info_t`
// structs whose total byte length is at most `isize::MAX`. The memory is exclusively
// owned by `guard` and is not mutated or freed until `guard` is dropped after the
// loop finishes copying the scalar fields into `queued_tasks`.
let tasks = unsafe {
core::slice::from_raw_parts(entry.queued_tasks, entry.num_queued_tasks)
};
for task in tasks {
queued_tasks.push(QueuedTaskDebugInfo {
ptr: task.ptr,
handler: task.handler,
initiating_dispatcher: task.initiating_dispatcher,
initiating_driver: task.initiating_driver as u64,
});
}
}
result.push(DispatcherDumpEntry {
driver: entry.driver as u64,
dispatcher_ptr: entry.dispatcher_ptr,
name,
scheduler_role,
options: entry.options,
synchronized: entry.synchronized,
allow_sync_calls: entry.allow_sync_calls,
state,
destroy_context,
destroy_user_initiated: entry
.has_destroy_user_initiated
.then_some(entry.destroy_user_initiated),
debug_stats: DispatcherDebugStats {
num_total_requests: entry.debug_stats.num_total_requests,
num_inlined_requests: entry.debug_stats.num_inlined_requests,
non_inlined: NonInlinedStats {
allow_sync_calls: entry.debug_stats.non_inlined.allow_sync_calls,
parallel_dispatch: entry.debug_stats.non_inlined.parallel_dispatch,
task: entry.debug_stats.non_inlined.task,
unknown_thread: entry.debug_stats.non_inlined.unknown_thread,
reentrant: entry.debug_stats.non_inlined.reentrant,
channel_wait_not_yet_registered: entry
.debug_stats
.non_inlined
.channel_wait_not_yet_registered,
no_thread_migration: entry.debug_stats.non_inlined.no_thread_migration,
},
},
queued_tasks,
});
}
result
}
/// Returns structured runtime diagnostic dumps for all threads currently spawned by the
/// driver runtime environment.
pub fn dump_all_threads(&self) -> Vec<ThreadDumpEntry> {
struct ThreadDumpEntriesGuard {
ptr: *mut fdf_thread_dump_entry_t,
count: usize,
}
impl Drop for ThreadDumpEntriesGuard {
fn drop(&mut self) {
if !self.ptr.is_null() {
// SAFETY: `self.ptr` and `self.count` were populated by a single call to
// `fdf_env_get_all_threads_dump`, which allocated the entry array and its
// nested string buffers on the C++ heap and transferred exclusive ownership to
// the caller. `ThreadDumpEntriesGuard` is dropped only after all temporary
// slices and `CStr` borrows derived from `self.ptr` have gone out of scope, so
// no dangling references can exist and the allocation is freed at most once.
unsafe {
fdf_env_free_all_threads_dump(self.ptr, self.count);
}
}
}
}
let mut raw_entries: *mut fdf_thread_dump_entry_t = null_mut();
let mut count: usize = 0;
// SAFETY: `raw_entries` and `count` are valid, initialized, and properly aligned stack
// variables passed via exclusive mutable references (`&mut`). The C++ implementation of
// `fdf_env_get_all_threads_dump` writes the newly allocated buffer pointer and element
// count into these out-parameters synchronously before returning and does not retain the
// addresses of `raw_entries` or `count`, preserving Rust's aliasing and lifetime rules.
unsafe {
fdf_env_get_all_threads_dump(&mut raw_entries, &mut count);
}
let guard = ThreadDumpEntriesGuard { ptr: raw_entries, count };
if guard.ptr.is_null() || guard.count == 0 {
return Vec::new();
}
// SAFETY: We verified that `guard.ptr` is non-null and `guard.count > 0`. By the FFI
// contract of `fdf_env_get_all_threads_dump`, `guard.ptr` points to a single contiguous
// heap allocation of `guard.count` initialized and properly aligned
// `fdf_thread_dump_entry_t` values whose total byte size does not exceed `isize::MAX`.
// Exclusive ownership of the allocation was transferred to this function and is held by
// `guard` for the entire lifetime of `entries`, ensuring the memory is neither mutated nor
// deallocated while the immutable slice borrow is active.
let entries = unsafe { core::slice::from_raw_parts(guard.ptr, guard.count) };
let mut result = Vec::with_capacity(guard.count);
for entry in entries {
let name = if entry.name.is_null() {
String::new()
} else {
// SAFETY: `entry.name` was checked to be non-null. `fdf_env_get_all_threads_dump`
// initializes `entry.name` via `CopyStringToHeap` (`malloc` + `memcpy` + NUL-terminator)
// from a valid string view, guaranteeing a valid, NUL-terminated sequence of bytes
// within a single allocation smaller than `isize::MAX`. The underlying buffer is
// exclusively owned by `guard` and is not mutated or freed until `guard` is dropped
// after this loop, and `.to_string_lossy()` immediately copies the bytes into an
// owned Rust `String`.
unsafe { ffi::CStr::from_ptr(entry.name) }.to_string_lossy().into_owned()
};
let scheduler_role = if entry.scheduler_role.is_null() {
String::new()
} else {
// SAFETY: `entry.scheduler_role` was checked to be non-null. By the FFI contract of
// `fdf_env_get_all_threads_dump`, it points to a heap-allocated, NUL-terminated C
// string created via `CopyStringToHeap` (`malloc` + `memcpy` + NUL-terminator) with
// size less than `isize::MAX`. The memory is exclusively owned by `guard`, remains
// immutable for the duration of this borrow, and is copied into an owned `String`
// before `guard` is dropped.
unsafe { ffi::CStr::from_ptr(entry.scheduler_role) }.to_string_lossy().into_owned()
};
result.push(ThreadDumpEntry { koid: entry.koid, name, scheduler_role });
}
result
}
/// Returns the current maximum number of threads which will be spawned for thread pool associated
/// with the given scheduler role.
///
/// |scheduler_role| is the name of the role which is passed when creating dispatchers.
pub fn get_thread_limit(&self, scheduler_role: &str) -> u32 {
let scheduler_role_ptr = scheduler_role.as_ptr() as *mut ffi::c_char;
let scheduler_role_len = scheduler_role.len();
unsafe { fdf_env_get_thread_limit(scheduler_role_ptr, scheduler_role_len) }
}
/// Sets the number of threads which will be spawned for thread pool associated with the given
/// scheduler role. It cannot shrink the limit less to a value lower than the current number of
/// threads in the thread pool.
///
/// |scheduler_role| is the name of the role which is passed when creating dispatchers.
/// |max_threads| is the number of threads to use as new limit.
pub fn set_thread_limit(&self, scheduler_role: &str, max_threads: u32) -> Result<(), Status> {
let scheduler_role_ptr = scheduler_role.as_ptr() as *mut ffi::c_char;
let scheduler_role_len = scheduler_role.len();
Status::ok(unsafe {
fdf_env_set_thread_limit(scheduler_role_ptr, scheduler_role_len, max_threads)
})
}
/// Returns the currently set options for the scheduler role as a uint32_t bitmask.
///
/// |scheduler_role| is the name of the role which is passed when creating dispatchers.
pub fn get_scheduler_role_opts(&self, scheduler_role: &str) -> u32 {
let scheduler_role_ptr = scheduler_role.as_ptr() as *mut ffi::c_char;
let scheduler_role_len = scheduler_role.len();
unsafe { fdf_env_get_scheduler_role_opts(scheduler_role_ptr, scheduler_role_len) }
}
/// When used with [`Self::set_scheduler_role_opts`], this will not allow any dispatchers on the
/// scheduler role to be created with `FDF_DISPATCHER_OPTION_ALLOW_SYNC_CALLS`.
pub const SCHEDULER_ROLE_OPTION_NO_SYNC_CALLS: u32 = FDF_SCHEDULER_ROLE_OPTION_NO_SYNC_CALLS;
/// Sets the options for the given scheduler role. This can be used to enforce restrictions
/// on the kinds of dispatchers that can be created on this scheduler role.
///
/// |scheduler_role| is the name of the role which is passed when creating dispatchers.
/// |options| is the new options for the scheduler role.
///
/// # Errors
///
/// [`Status::INVALID_ARGS`]: |options| contains unknown or invalid options.
/// [`Status::ERR_NOT_SUPPORTED`]: |options| contains an option that wouldn't allow a dispatcher
/// that already exists on this scheduler role.
pub fn set_scheduler_role_opts(
&self,
scheduler_role: &str,
options: u32,
) -> Result<(), Status> {
let scheduler_role_ptr = scheduler_role.as_ptr() as *mut ffi::c_char;
let scheduler_role_len = scheduler_role.len();
Status::ok(unsafe {
fdf_env_set_scheduler_role_opts(scheduler_role_ptr, scheduler_role_len, options)
})
}
/// Gets the driver currently running on the thread identified by |thread_koid|, if the thread
/// is running on this driver host with a driver.
pub fn get_driver_on_thread_koid(&self, thread_koid: zx::Koid) -> Option<UnownedDriver> {
let mut driver = std::ptr::null();
unsafe {
Status::ok(fdf_env_get_driver_on_tid(thread_koid.raw_koid(), &mut driver)).ok()?;
}
if driver.is_null() { None } else { Some(UnownedDriver { inner: driver }) }
}
/// Registers a callback which is triggered whenever the stall scanner should run.
pub fn register_stall_scanner(&self, scanner: StallScanner) {
unsafe {
fdf_env_register_stall_scanner(scanner.into_ptr());
}
}
}
/// A registration handle returned by [`Driver::register_resume_requester`].
/// The user MUST call `unregister` to unregister the resume requester when it is no longer valid.
#[derive(Debug)]
pub struct ResumeRequesterRegistration {
driver_ptr: *const ffi::c_void,
requester_ptr: *mut fdf_env_resume_requester_t,
}
// SAFETY: The runtime API that we call in this object (fdf_env_register_resume_requester)
// is thread-safe and can be called from any thread. We are also the exclusive maintainer of
// requester_ptr's lifetime.
unsafe impl Send for ResumeRequesterRegistration {}
impl ResumeRequesterRegistration {
/// Unregisters the resume requester from the runtime and frees the memory associated with it.
pub fn unregister(mut self) {
// Unregister the callback from the runtime.
// SAFETY: The null pointer is handled correctly by the runtime. If driver_ptr is no longer valid
// in the driver runtime, it will be treated as a no-op.
unsafe {
fdf_sys::fdf_env_register_resume_requester(self.driver_ptr, null_mut());
}
// Reconstitute the box and free it.
// SAFETY: requester_ptr was created using Box::leak(Box::new(self)).
// This is the only location that we re-create the Box, with exclusive ownership of self.
let requester = unsafe { Box::from_raw(self.requester_ptr as *mut ResumeRequester) };
drop(requester);
self.requester_ptr = null_mut();
}
}
/// The lifecycle state of a dispatcher.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DispatcherState {
/// The dispatcher is running and accepting callbacks.
Running,
/// The dispatcher is currently shutting down.
ShuttingDown,
/// The dispatcher has completed shutdown.
Shutdown,
/// The dispatcher has been destroyed.
Destroyed,
}
/// Breakdown of reasons why requests were not inlined by the driver runtime.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct NonInlinedStats {
/// Calling from a non-blocking to a blocking (`ALLOW_SYNC_CALLS`) dispatcher.
pub allow_sync_calls: u64,
/// Another thread was already dispatching a request.
pub parallel_dispatch: u64,
/// The request was a task.
pub task: u64,
/// The request was queued from an unknown thread.
pub unknown_thread: u64,
/// The request would have been reentrant.
pub reentrant: u64,
/// Channel wait was not yet registered when the message was received.
pub channel_wait_not_yet_registered: u64,
/// Called into a dispatcher that wasn't allowed to migrate threads.
pub no_thread_migration: u64,
}
/// Request statistics for a dispatcher.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DispatcherDebugStats {
/// Total number of requests processed by this dispatcher.
pub num_total_requests: u64,
/// Number of requests that were inlined.
pub num_inlined_requests: u64,
/// Breakdown of reasons why requests were not inlined.
pub non_inlined: NonInlinedStats,
}
/// Diagnostic information for a task queued on a dispatcher.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct QueuedTaskDebugInfo {
/// Address of the queued `async_task_t`.
pub ptr: u64,
/// Address of the task handler function.
pub handler: u64,
/// Address of the dispatcher that queued this task, if queued from a runtime thread.
pub initiating_dispatcher: u64,
/// Address of the driver that queued this task, if queued from a runtime thread.
pub initiating_driver: u64,
}
/// Structured diagnostic dump entry for a dispatcher in the driver runtime.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DispatcherDumpEntry {
/// Address of the driver owner of this dispatcher.
pub driver: u64,
/// Address of the dispatcher object.
pub dispatcher_ptr: u64,
/// Name of the dispatcher.
pub name: String,
/// Scheduler role configured for the dispatcher.
pub scheduler_role: String,
/// Options mask the dispatcher was created with.
pub options: u32,
/// Whether the dispatcher is synchronized.
pub synchronized: bool,
/// Whether the dispatcher allows blocking synchronous calls.
pub allow_sync_calls: bool,
/// Current lifecycle state of the dispatcher.
pub state: DispatcherState,
/// Name of the dispatcher that initiated destruction, if `Destroy` was called.
pub destroy_context: String,
/// Whether `Destroy` was user-initiated (`true`) or environment-initiated (`false`).
pub destroy_user_initiated: Option<bool>,
/// Request and inlining statistics for the dispatcher.
pub debug_stats: DispatcherDebugStats,
/// Currently queued tasks on the dispatcher.
pub queued_tasks: Vec<QueuedTaskDebugInfo>,
}
/// Structured diagnostic dump entry for a thread spawned by the driver runtime.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ThreadDumpEntry {
/// Kernel object ID (KOID) of the thread.
pub koid: u64,
/// Name of the thread.
pub name: String,
/// Scheduler role of the thread pool that spawned this thread.
pub scheduler_role: String,
}