Expand description
CUDA Graph RAII helpers for production graph capture/replay.
This module intentionally stays close to the CUDA driver API. The bounded CSM CUDA Graph path needs explicit graph lifetime ownership and node inventory before it can safely update graph-exec parameters for runtime pointers and capacity classes.
§Cold lifecycle and progress
Releasing the last module or graph owner can synchronously wait for recorded execution events. During capture, destruction is deferred: finishing the last capture can therefore wait for another owner’s earlier executions. Capture setup and module loading/replacement can also drain pending destruction. These are cold lifecycle boundaries, outside the measured resident replay; include their cost in end-to-end measurements. Failed memory-operation cleanup can require a barrier on the entire retained context, including after its original host thread exits without a usable completion event. This recovery runs only in the cold retirement queue with capture excluded; ordinary enqueue and commit do not add that barrier.
An execution event covers all preceding work on its stream, including transitive waits, not just kernels using the retiring resource. Before any boundary that can drain destruction, that work must be able to finish without this call returning, a new module load or capture, launching the graph still being captured, or releasing a caller-held lock or Python GIL. Persistent kernels need an independently progressing stop path established beforehand. Do not rely on CUDA callbacks to advance this teardown, or destroy owners from a CUDA callback. The registry mutex is released during waits/destruction; new captures remain excluded, while already-loaded work can still be submitted. Context-barrier recovery imposes that same progress requirement on all earlier work in the retained context, not just work on one retiring stream.
Recorded events or a successful barrier covering the actual submissions prove completion. EndCapture and unrecorded events do not. Unknown completion retains the concrete resources for diagnosis; it is neither successful release nor a normal lifetime policy. Raw graph/function users must retain their exact resource owners through all uses and future replays, and establish completion before releasing them.
Structs§
- Captured
Cuda Graph - Instantiated CUDA Graph with owned graph + exec handles.
- Conditional
Cuda Graph Body - CUDA-owned body graph produced while adding one conditional-WHILE node.
- Conditional
Cuda Graph Sequence Builder - Builds one dependency-ordered parent graph containing ordinary captured segments, one-shot conditional-IF bodies and conditional-WHILE loops.
- CsmCuda
Graph Key - Cuda
Graph Node - Scan
Topology