cuda.core.Stream

class cuda.core.Stream(*args, **kwargs)

Represent a queue of GPU operations that are executed in a specific order.

Applications use streams to control the order of execution for GPU work. Work within a single stream are executed sequentially. Whereas work across multiple streams can be further controlled using stream priorities and Event managements.

Advanced users can utilize default streams for enforce complex implicit synchronization behaviors.

Directly creating a Stream is not supported due to ambiguity. New streams should instead be created through a Device object, or created directly through using an existing handle using Stream.from_handle().

Methods

__init__(*args, **kwargs)

close(self)

Destroy the stream.

Releases the stream handle. For owned streams, this destroys the underlying CUDA stream. For borrowed streams, this releases the reference and allows the Python owner to be GC’d.

create_graph_builder(self) → GraphBuilder

Create a new GraphBuilder object.

The new graph builder will be associated with this stream.

Returns:

Newly created graph builder object.

Return type:

GraphBuilder

static from_handle(int handle: int) → Stream

Create a new Stream object from a foreign stream handle.

Uses a cudaStream_t pointer address represented as a Python int to create a new Stream object.

Note

Stream lifetime is not managed, foreign object must remain alive while this steam is active.

Parameters:

handle (int) – Stream handle representing the address of a foreign stream object.

Returns:

Newly created stream object.

Return type:

Stream

record(

self,

event: Event = None,

options: EventOptions = None,

) → Event

Record an event onto the stream.

Creates an Event object (or reuses the given one) by recording on the stream.

Parameters:

• event (Event, optional) – Optional event object to be reused for recording.

• options (EventOptions, optional) – Customizable dataclass for event creation options.

Returns:

Newly created event object.

Return type:

Event

sync(self)

Synchronize the stream.

wait(self, event_or_stream: Event | Stream)

Wait for a CUDA event or a CUDA stream.

Waiting for an event or a stream establishes a stream order.

If a Stream is provided, then wait until the stream’s work is completed. This is done by recording a new Event on the stream and then waiting on it.

Attributes

context

Context

Return the Context associated with this stream.

Type:

Stream.context

device

Device

Return the Device singleton associated with this stream.

Note

The current context on the device may differ from this stream’s context. This case occurs when a different CUDA context is set current after a stream is created.

Type:

Stream.device

handle

cuda.bindings.driver.CUstream

Return the underlying CUstream object.

Caution

This handle is a Python object. To get the memory address of the underlying C handle, call int(Stream.handle).

Type:

Stream.handle

is_nonblocking

bool

Return True if this is a nonblocking stream, otherwise False.

Type:

Stream.is_nonblocking

priority

int

Return the stream priority.

Type:

Stream.priority