Crate gpu_async_reactor

Expand description

Await GPU work as a memory descriptor.

A GPU stream stores a sequence number into a word of host-visible memory behind its work; that word is to device completion what a file descriptor is to I/O readiness. This crate makes it a first-class awaitable source and supplies the pieces around it:

CompletionLine / MemoryDescriptor: one 64-byte line of eight completion words, and one word reaching one sequence number.
WaitPlan / WaitBands: how a host waits (block, poll, or park on the word with a status backstop), optionally after sleeping to a predicted completion; typed, parsed once.
PointTable: the deadline estimator (min of recent exact residuals per readback point, late wakes censored downward).
CompletionPort + wait: the per-backend port and the async driver that runs a plan.
Executor + Reactor: a small single-threaded executor whose idle sleeps to the earliest predicted deadline, then parks on the completion line; ready tasks run between waits.
ExecutorKind + resolve: the selectable executor (naive, gpu-reactor, io-uring) with a declared fallback chain, a coded warning, and an opt-in strict refusal.
Error / ErrorCode: coded errors, one append-only registry.

The core is no_std + alloc and forbids unsafe. Vendor code sits behind features in backend (cuda, hip, metal, wordwait) and hosts in host (std, tokio, io-uring). See the README for measured numbers and the safety model.

Modules§

backend: Vendor backends, each behind its cargo feature. This is the only place unsafe is allowed: every block carries a SAFETY: comment, and every public item is safe to call.
host: Hosts: the clocks, timers and idles a binary picks. The core never names one.

Macros§

error: Build an Error: error!(Code, arg, …); each argument is anything Display.

Structs§

Alarmed: The reactor’s sleep future (its Timer).
Band: One band: plan runs from from_rows rows up to the next band’s edge.
Bands: The bands, in edge order (module invariants).
CompletionLine: A 64-byte aligned line of completion words.
DeadlinePlan: The deadline fields.
DurNs: A duration in nanoseconds.
Error: A coded error: an ErrorCode and its arguments.
Executor: A single-threaded FILL executor over tasks of type F.
ExecutorCaps: What a host offers the executors, probed once.
Fallback: One link of the declared fallback chain.
HostCaps: What a host offers, probed once at boot by the host (never by the core).
ManualClock: A clock that moves only when told to; clones share it.
ManualTimer: The Timer of one ManualClock; it fires only when that clock moves.
MemoryDescriptor: One awaitable completion: word slot of line reaching target. Sequence numbers increase by one per store, so “reached” is word >= target in wrapping order (a later store that lands before the waiter looks still completes it).
MonoNs: Monotonic nanoseconds from a host-chosen origin.
PointEstimate: One readback point’s residual estimate (a ring of the last samples).
PointTable: The estimates of every readback point a host has waited at, keyed by K (the host’s point identity, e.g. a call site). Runtime measurement, not a decision input.
Reactor: The reactor of one executor: registrations made by the futures it hands out.
Ready: The future of Reactor::ready.
Resolution: A resolved setting: what was asked, what runs, and the warning when they differ.
Resolved: The plan a host runs, and the coded warning when a fallback was taken.
RunStats: What a Executor::run did: the work it ran and the idle it measured.
Slot: The slot of a word in a CompletionLine (0..LINE_WORDS, checked once at construction).
StepRows: The rows of the current decode step: written once per step by the router that launches it, read by every wait of the host that owns the bands. 0 until the first step.
WaitPlan: How a host waits at a readback point.
WaitReport: What one wait did, for the estimator (outcome) and the host’s counters.

Enums§

Capability: A host capability a park needs.
ErrorCode: The identity of an Error: append-only, a number is never reused.
ExecutorKind: How a waiting thread runs a wait.
Outcome: What one wait observed at its readback point.
Park: How the rest of a wait is spent.
ParkKind: A park’s kind, without its fields.
Strictness: Whether a setting may fall back when its value is unavailable.
Turn: What one Reactor::turn did.
WaitKind: How one wait ended.

Constants§

BANDS_MAX: The most bands a plan may state.
FALLBACKS: the whole chain, as data. The executor never chooses; WaitPlan::resolve walks this table once at boot. The chain ends at QueryPoll, which needs nothing and runs on every host; Block, the vendor’s blocking wait, is the conservative arm a plan may name (declared, not a default).
LINE_WORDS: Completion words per line.
WINDOW_MAX: The largest window a deadline plan may state.

Traits§

Clock: The host’s monotonic clock: the core’s only time source.
CompletionPort: One wait on device work, implemented per backend (the core names no vendor). query answers at once; the others take time and are awaited: a host that runs them on the waiting thread returns a ready future, an executor’s pend. Errors are the port’s own type and pass through wait unchanged.
Declared: A setting value with a declared fallback chain.
Idle: How an executor’s thread idles when no task is ready: the host’s blocking primitives. Only the executor calls these, and only between task polls.
Timer: The host’s sleep. A host that runs a wait inline returns a future that is ready on its first poll (it slept already); an executor’s timer pends until its deadline.

Functions§

block_on: Run one future to completion on an executor of its own; see Executor::run.
reached: Whether word slot of line has reached target in wrapping sequence order.
resolve: Resolve requested against caps: walk the declared chain while the value cannot run.
run_inline: Poll fut once with a no-op waker: for hosts whose every future is ready on the first poll (a thread that sleeps and parks inline). A pending poll is a bug in such a host, reported as PendedInline naming site, never a hang.
wait: Run plan over port. sleep_ns is the point’s estimate (PointTable::sleep_ns) and is used only when plan.predict is set.
yield_now: Yield to the executor once: the task is woken at once and runs again after every other ready task had its turn (cooperative slicing of CPU work between waits).

Type Aliases§

Result: Result with this crate’s Error.
WaitBands: The requested bands, as the lever states them.