cuda-api-wrappers
Thin C++-flavored wrappers for the CUDA Runtime API
cuda::stream Namespace Reference

Definitions and functionality related to CUDA streams (not including the device wrapper type stream_t itself) More...

Typedefs

using handle_t = CUstream
 The CUDA driver's raw handle for streams.
 
using priority_t = int
 CUDA streams have a scheduling priority, with lower values meaning higher priority. More...
 
using callback_t = CUstreamCallback
 The CUDA driver's raw handle for a host-side callback function.
 

Enumerations

enum  : bool {
  implicitly_synchronizes_with_default_stream = true,
  no_implicit_synchronization_with_default_stream = false,
  sync = implicitly_synchronizes_with_default_stream,
  async = no_implicit_synchronization_with_default_stream,
  blocking = sync,
  nonblocking = async
}
 
enum  wait_condition_t : unsigned {
  greater_or_equal_to = CU_STREAM_WAIT_VALUE_GEQ,
  geq = CU_STREAM_WAIT_VALUE_GEQ,
  equality = CU_STREAM_WAIT_VALUE_EQ,
  equals = CU_STREAM_WAIT_VALUE_EQ,
  nonzero_after_applying_bitmask = CU_STREAM_WAIT_VALUE_AND,
  one_bits_overlap = CU_STREAM_WAIT_VALUE_AND,
  bitwise_and = CU_STREAM_WAIT_VALUE_AND,
  zero_bits_overlap = CU_STREAM_WAIT_VALUE_NOR,
  bitwise_nor = CU_STREAM_WAIT_VALUE_NOR
}
 Kinds of conditions to apply to a value in GPU global memory when waiting on that value, i.e. More...
 
enum  : priority_t { default_priority = 0 }
 

Functions

stream_t create (const device_t &device, bool synchronizes_with_default_stream, priority_t priority=stream::default_priority)
 Create a new stream (= queue) in the primary execution context of a CUDA device. More...
 
stream_t create (const context_t &context, bool synchronizes_with_default_stream, priority_t priority=stream::default_priority, bool hold_pc_refcount_unit=false)
 Create a new stream (= queue) in a CUDA execution context. More...
 
stream_t wrap (device::id_t device_id, context::handle_t context_handle, handle_t stream_handle, bool take_ownership=false, bool hold_pc_refcount_unit=false) noexcept
 Wrap an existing stream in a stream_t instance. More...
 

Variables

const stream::handle_t default_stream_handle = nullptr
 The CUDA runtime provides a default stream on which work is scheduled when no stream is specified; for those API calls where you need to specify the relevant stream's ID, and want to specify the default, this is what you use.
 

Detailed Description

Definitions and functionality related to CUDA streams (not including the device wrapper type stream_t itself)

Typedef Documentation

◆ priority_t

using cuda::stream::priority_t = typedef int

CUDA streams have a scheduling priority, with lower values meaning higher priority.

The types represents a larger range of values than those actually used; they can be obtained by device_t::stream_priority_range() .

Enumeration Type Documentation

◆ anonymous enum

anonymous enum : priority_t
Enumerator
default_priority 

the scheduling priority of a stream created without specifying any other priority value

◆ wait_condition_t

Kinds of conditions to apply to a value in GPU global memory when waiting on that value, i.e.

on what condition to stop waiting.

Function Documentation

◆ create() [1/2]

stream_t cuda::stream::create ( const device_t device,
bool  synchronizes_with_default_stream,
priority_t  priority = stream::default_priority 
)
inline

Create a new stream (= queue) in the primary execution context of a CUDA device.

Parameters
devicethe device on which a stream is to be created
synchronizes_with_default_streamif true, no work on this stream will execute concurrently with work from the default stream (stream 0)
prioritypriority of tasks on the stream, relative to other streams, for execution scheduling; lower numbers represent higher properties; each device has a range of priorities, which can be obtained using device_t::stream_priority_range()
Returns
The newly-created stream

◆ create() [2/2]

stream_t cuda::stream::create ( const context_t context,
bool  synchronizes_with_default_stream,
priority_t  priority = stream::default_priority,
bool  hold_pc_refcount_unit = false 
)
inline

Create a new stream (= queue) in a CUDA execution context.

Parameters
contextthe execution context in which to create the stream
synchronizes_with_default_streamif true, no work on this stream will execute concurrently with work from the default stream (stream 0)
prioritypriority of tasks on the stream, relative to other streams, for execution scheduling; lower numbers represent higher properties; each device has a range of priorities, which can be obtained using device_t::stream_priority_range()
hold_pc_refcount_unitwhen the stream's context is a device's primary context, this controls whether that context must be kept active while the steam continues to exist
Returns
The newly-created stream

◆ wrap()

stream_t cuda::stream::wrap ( device::id_t  device_id,
context::handle_t  context_handle,
stream::handle_t  stream_handle,
bool  take_ownership = false,
bool  hold_pc_refcount_unit = false 
)
inlinenoexcept

Wrap an existing stream in a stream_t instance.

Note
This is a named constructor idiom, existing of direct access to the ctor of the same signature, to emphasize that a new stream is not created.
Parameters
device_idID of the device for which the stream is defined
context_handlehandle of the context in which the stream was created
stream_handlehandle of the pre-existing stream
take_ownershipWhen set to false, the stream will not be destroyed along with the wrapper; use this setting when temporarily working with a stream existing irrespective of the current context and outlasting it. When set to true, the proxy class will act as it does usually, destroying the stream when being destructed itself.
hold_pc_refcount_unitwhen the stream's context is a device's primary context, this controls whether that context must be kept active while the stream continues to exist
Returns
an instance of the stream proxy class, with the specified device-stream combination.