Struct StreamCapture 

pub struct StreamCapture { /* private fields */ }

A CPU-side model of one or more concurrently-capturing CUDA streams.

Operations are recorded into a single underlying ComputeGraph; the capture session tracks, per stream, the most recently recorded node so it can wire in the implicit sequential dependency between successive ops on the same stream. Events bridge dependencies across streams.

Example

use oxicuda_graph::capture::{StreamCapture, CaptureEvent, CaptureStatus};
use oxicuda_graph::node::{MemcpyDir, StreamId};

let mut cap = StreamCapture::new();
let main = StreamId(0);
let side = StreamId(1);

cap.begin_capture(main).unwrap();
cap.begin_capture(side).unwrap();
// origin op on the main stream
let up = cap.record_memcpy(main, "upload", MemcpyDir::HostToDevice, 4096).unwrap();

// fork: side stream waits for an event recorded on the main stream
let ev = CaptureEvent(0);
cap.record_event(main, ev).unwrap();
cap.wait_event(side, ev).unwrap();
let k = cap.record_kernel(side, "relu", 4, 256, 0).unwrap();

// join back into the main stream
let ev2 = CaptureEvent(1);
cap.record_event(side, ev2).unwrap();
cap.wait_event(main, ev2).unwrap();
let dn = cap.record_memcpy(main, "download", MemcpyDir::DeviceToHost, 4096).unwrap();

assert_eq!(cap.status(main), CaptureStatus::Active);
let graph = cap.end_capture(main).unwrap();
// up → k (via fork) and k → dn (via join) must hold.
assert!(graph.is_reachable(up, k));
assert!(graph.is_reachable(k, dn));

Implementations

impl StreamCapture

pub fn new() -> Self

Creates an empty capture session with no streams capturing.

pub fn status(&self, stream: StreamId) -> CaptureStatus

Returns the capture status of stream.

A stream that was never begun reports CaptureStatus::None.

pub fn is_capturing(&self) -> bool

Returns true if any stream in this session is actively capturing.

pub fn begin_capture(&mut self, stream: StreamId) -> GraphResult<()>

Begins capture on stream.

Errors

Returns GraphError::Internal if stream is already capturing.

pub fn record_kernel( &mut self, stream: StreamId, function_name: &str, num_blocks: u32, threads_per_block: u32, shared_mem: u32, ) -> GraphResult<NodeId>

Records a kernel-launch operation on a capturing stream.

Returns the NodeId of the created node.

Errors

Returns GraphError::Internal if stream is not actively capturing.

pub fn record_memcpy( &mut self, stream: StreamId, name: &str, dir: MemcpyDir, size_bytes: usize, ) -> GraphResult<NodeId>

Records a memcpy operation on a capturing stream.

Errors

Returns GraphError::Internal if stream is not actively capturing.

pub fn record_memset( &mut self, stream: StreamId, name: &str, size_bytes: usize, value: u8, ) -> GraphResult<NodeId>

Records a memset operation on a capturing stream.

Errors

Returns GraphError::Internal if stream is not actively capturing.

pub fn record_host_callback( &mut self, stream: StreamId, label: &str, ) -> GraphResult<NodeId>

Records a host-callback operation on a capturing stream.

Errors

Returns GraphError::Internal if stream is not actively capturing.

pub fn record_event( &mut self, stream: StreamId, event: CaptureEvent, ) -> GraphResult<()>

Records event on stream, capturing the current head node so that a later wait_event can depend on it.

This is the “fork” half of fork / join capture. Recording an event on a stream that has issued no operations is a no-op source (the event carries no dependency).

Errors

Returns GraphError::Internal if stream is not actively capturing.

pub fn wait_event( &mut self, stream: StreamId, event: CaptureEvent, ) -> GraphResult<()>

Makes stream wait on event, threading the cross-stream dependency.

This is the “join” half of fork / join capture: every operation recorded on stream after this wait depends on the node that recorded event. In CUDA semantics a stream-wait gates only subsequent work, so the dependency is parked and attached to the next op recorded on stream (it never re-orders operations already issued on the stream).

A cycle is only detectable once the dependency is materialised against the next recorded op; see record_kernel and friends.

Errors

Returns GraphError::Internal if stream is not actively capturing.

pub fn end_capture(self, stream: StreamId) -> GraphResult<ComputeGraph>

Ends capture on stream, returning the assembled ComputeGraph.

Consumes the entire capture session: a graph is captured once.

Errors

• GraphError::Internal if stream was not actively capturing.
• GraphError::ValidationFailed (via GraphError::Internal) if any stream was invalidated during capture.

pub fn node_count(&self) -> usize

Returns the number of nodes recorded so far.

pub fn invalidate(&mut self, stream: StreamId) -> GraphResult<()>

Forcibly invalidates capture on stream, modelling an illegal operation that CUDA would reject (e.g. a disallowed cross-stream synchronisation, or unsafe memory operation issued during capture).

An invalidated stream can no longer record ops or be ended successfully; the whole session is poisoned to mirror CUDA’s behaviour where one stream’s invalidation aborts the capture.

Errors

Returns GraphError::Internal if stream is not actively capturing.

Trait Implementations

impl Debug for StreamCapture

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StreamCapture

fn default() -> StreamCapture

Returns the “default value” for a type.