atomr_accel/completion.rs
1//! `CompletionStrategy` — async wakeup contract for kernel
2//! completion. Promoted to the core so every backend can plug into
3//! the same family (host-fn callback, sync block, polled query).
4
5use async_trait::async_trait;
6
7use crate::backend::AccelBackend;
8use crate::error::AccelError;
9
10/// Strategy for awaiting kernel completion on a stream.
11///
12/// Three canonical implementations live in each backend:
13/// - **HostFn** — `cuLaunchHostFunc` / `hipLaunchHostFunc` /
14/// `MTLCommandBuffer.addCompletedHandler` callback. Sub-µs
15/// wakeup, no host-side blocking.
16/// - **Sync** — explicit `cudaStreamSynchronize`. Easy reasoning,
17/// parks a host thread.
18/// - **Polled** — periodic `cuEventQuery` with a timeout. Hard
19/// upper bound at the cost of a polling loop.
20#[async_trait]
21pub trait CompletionStrategy<B: AccelBackend>: Send + Sync + 'static {
22 /// Resolve once every kernel previously enqueued on `stream`
23 /// has finished. `Ok(())` on completion; `Err` if the device
24 /// poisoned mid-flight.
25 async fn await_completion(&self, stream: &B::Stream) -> Result<(), AccelError>;
26}