gpu_async_reactor/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Await GPU work as a **memory descriptor**.
4//!
5//! A GPU stream stores a sequence number into a word of host-visible memory behind its work;
6//! that word is to device completion what a file descriptor is to I/O readiness. This crate
7//! makes it a first-class awaitable source and supplies the pieces around it:
8//!
9//! - [`CompletionLine`] / [`MemoryDescriptor`]: one 64-byte line of eight completion words, and
10//!   one word reaching one sequence number.
11//! - [`WaitPlan`] / [`WaitBands`]: how a host waits (block, poll, or park on the word with a
12//!   status backstop), optionally after sleeping to a predicted completion; typed, parsed once.
13//! - [`PointTable`]: the deadline estimator (min of recent exact residuals per readback point,
14//!   late wakes censored downward).
15//! - [`CompletionPort`] + [`wait`]: the per-backend port and the async driver that runs a plan.
16//! - [`Executor`] + [`Reactor`]: a small single-threaded executor whose idle sleeps to the
17//!   earliest predicted deadline, then parks on the completion line; ready tasks run between
18//!   waits.
19//! - [`ExecutorKind`] + [`resolve`]: the selectable executor (`naive`, `gpu-reactor`,
20//!   `io-uring`) with a declared fallback chain, a coded warning, and an opt-in strict refusal.
21//! - [`Error`] / [`ErrorCode`]: coded errors, one append-only registry.
22//!
23//! The core is `no_std` + `alloc` and forbids `unsafe`. Vendor code sits behind features in
24//! [`backend`] (`cuda`, `hip`, `metal`, `wordwait`) and hosts in [`host`] (`std`, `tokio`,
25//! `io-uring`). See the README for measured numbers and the safety model.
26#![no_std]
27#![cfg_attr(docsrs, feature(doc_cfg))]
28
29extern crate alloc;
30#[cfg(feature = "std")]
31extern crate std;
32
33#[path = "core/completion_core.rs"]
34mod core;
35
36#[path = "backend/vendor_backends.rs"]
37pub mod backend;
38#[path = "host/host_adapters.rs"]
39pub mod host;
40
41pub use crate::core::bands::{BANDS_MAX, Band, Bands, StepRows, WaitBands};
42pub use crate::core::declared::{
43    Declared, ExecutorCaps, ExecutorKind, Resolution, Strictness, resolve,
44};
45pub use crate::core::error::{Error, ErrorCode, Result};
46pub use crate::core::estimator::{Outcome, PointEstimate, PointTable};
47pub use crate::core::executor::{Executor, RunStats, block_on, run_inline, yield_now};
48pub use crate::core::line::{CompletionLine, LINE_WORDS, MemoryDescriptor, Slot, reached};
49pub use crate::core::manual::{ManualClock, ManualTimer};
50pub use crate::core::plan::{
51    Capability, DeadlinePlan, FALLBACKS, Fallback, HostCaps, Park, ParkKind, Resolved, WINDOW_MAX,
52    WaitPlan,
53};
54pub use crate::core::reactor::{Alarmed, Idle, Reactor, Ready, Turn};
55pub use crate::core::time::{Clock, DurNs, MonoNs, Timer};
56pub use crate::core::wait::{CompletionPort, WaitKind, WaitReport, wait};
gpu_async_reactor/lib.rs

gpu_async_reactor/
lib.rs
