cuda.core.experimental.Stream#

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

Bases: object

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.

Destroy the stream if we own it. Borrowed foreign stream object will instead have their references released.

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

close(self)#

Destroy the stream.

Destroy the stream if we own it. Borrowed foreign stream object will instead have their references released.

context#

Context

Return the Context associated with this stream.

Type:: Stream.context

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

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

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

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

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.