CUDA Runtime API :: CUDA Toolkit Documentation

6.5. 流管理

本节介绍CUDA运行时应用程序编程接口的流管理功能。

类型定义

typedef void(CUDART_CB* cudaStreamCallback_t )( cudaStream_t stream, cudaError_t status, void* userData )

Functions

__host__ cudaError_t cudaCtxResetPersistingL2Cache ( void ): Resets all persisting lines in cache to normal status.
__host__ cudaError_t cudaStreamAddCallback ( cudaStream_t stream, cudaStreamCallback_t callback, void* userData, unsigned int flags ): Add a callback to a compute stream.
__host__ cudaError_t cudaStreamAttachMemAsync ( cudaStream_t stream, void* devPtr, size_t length = 0, unsigned int flags = cudaMemAttachSingle ): Attach memory to a stream asynchronously.
__host__ cudaError_t cudaStreamBeginCapture ( cudaStream_t stream, cudaStreamCaptureMode mode ): Begins graph capture on a stream.
__host__ cudaError_t cudaStreamBeginCaptureToGraph ( cudaStream_t stream, cudaGraph_t graph, const cudaGraphNode_t* dependencies, const cudaGraphEdgeData* dependencyData, size_t numDependencies, cudaStreamCaptureMode mode ): Begins graph capture on a stream to an existing graph.
__host__ cudaError_t cudaStreamCopyAttributes ( cudaStream_t dst, cudaStream_t src ): Copies attributes from source stream to destination stream.
__host__ cudaError_t cudaStreamCreate ( cudaStream_t* pStream ): Create an asynchronous stream.
__host__ __device__ cudaError_t cudaStreamCreateWithFlags ( cudaStream_t* pStream, unsigned int flags ): Create an asynchronous stream.
__host__ cudaError_t cudaStreamCreateWithPriority ( cudaStream_t* pStream, unsigned int flags, int priority ): Create an asynchronous stream with the specified priority.
__host__ __device__ cudaError_t cudaStreamDestroy ( cudaStream_t stream ): Destroys and cleans up an asynchronous stream.
__host__ cudaError_t cudaStreamEndCapture ( cudaStream_t stream, cudaGraph_t* pGraph ): Ends capture on a stream, returning the captured graph.
__host__ cudaError_t cudaStreamGetAttribute ( cudaStream_t hStream, cudaStreamAttrID attr, cudaStreamAttrValue* value_out ): Queries stream attribute.
__host__ cudaError_t cudaStreamGetCaptureInfo ( cudaStream_t stream, cudaStreamCaptureStatus ** captureStatus_out, unsigned long long* id_out = 0, cudaGraph_t* graph_out = 0, const cudaGraphNode_t** dependencies_out = 0, size_t* numDependencies_out = 0 ): Query a stream's capture state.
__host__ cudaError_t cudaStreamGetCaptureInfo_v3 ( cudaStream_t stream, cudaStreamCaptureStatus ** captureStatus_out, unsigned long long* id_out = 0, cudaGraph_t* graph_out = 0, const cudaGraphNode_t** dependencies_out = 0, const cudaGraphEdgeData** edgeData_out = 0, size_t* numDependencies_out = 0 ): Query a stream's capture state (12.3+).
__host__ cudaError_t cudaStreamGetDevice ( cudaStream_t hStream, int* device ): Query the device of a stream.
__host__ cudaError_t cudaStreamGetFlags ( cudaStream_t hStream, unsigned int* flags ): Query the flags of a stream.
__host__ cudaError_t cudaStreamGetId ( cudaStream_t hStream, unsigned long long* streamId ): Query the Id of a stream.
__host__ cudaError_t cudaStreamGetPriority ( cudaStream_t hStream, int* priority ): Query the priority of a stream.
__host__ cudaError_t cudaStreamIsCapturing ( cudaStream_t stream, cudaStreamCaptureStatus ** pCaptureStatus ): Returns a stream's capture status.
__host__ cudaError_t cudaStreamQuery ( cudaStream_t stream ): Queries an asynchronous stream for completion status.
__host__ cudaError_t cudaStreamSetAttribute ( cudaStream_t hStream, cudaStreamAttrID attr, const cudaStreamAttrValue* value ): Sets stream attribute.
__host__ cudaError_t cudaStreamSynchronize ( cudaStream_t stream ): Waits for stream tasks to complete.
__host__ cudaError_t cudaStreamUpdateCaptureDependencies ( cudaStream_t stream, cudaGraphNode_t* dependencies, size_t numDependencies, unsigned int flags = 0 ): Update the set of dependencies in a capturing stream (11.3+).
__host__ cudaError_t cudaStreamUpdateCaptureDependencies_v2 ( cudaStream_t stream, cudaGraphNode_t* dependencies, const cudaGraphEdgeData* dependencyData, size_t numDependencies, unsigned int flags = 0 ): Update the set of dependencies in a capturing stream (12.3+).
__host__ __device__ cudaError_t cudaStreamWaitEvent ( cudaStream_t stream, cudaEvent_t event, unsigned int flags = 0 ): Make a compute stream wait on an event.
__host__ cudaError_t cudaThreadExchangeStreamCaptureMode ( cudaStreamCaptureMode ** mode ): Swaps the stream capture interaction mode for a thread.

类型定义

void(CUDART_CB* cudaStreamCallback_t )( cudaStream_t stream, cudaError_t status, void* userData ): 流回调函数的类型。

Functions

__host__ cudaError_t cudaCtxResetPersistingL2Cache ( void )

将缓存中所有持久化的行重置为正常状态。

cudaSuccess,

描述

将缓存中所有持久化行重置为正常状态。在函数返回时生效。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaAccessPolicyWindow

__host__ cudaError_t cudaStreamAddCallback ( cudaStream_t stream, cudaStreamCallback_t callback, void* userData, unsigned int flags )

向计算流添加回调函数。

参数

stream: - Stream to add callback to
callback: - The function to call once preceding stream operations are complete
userData: - User specified data to be passed to the callback function
flags: - Reserved for future use, must be 0

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorInvalidValue, cudaErrorNotSupported

描述

Note:

此函数计划最终弃用并移除。如果您不需要在设备错误时执行回调，请考虑使用cudaLaunchHostFunc。此外，与cudaLaunchHostFunc不同，此函数不支持与cudaStreamBeginCapture和cudaStreamEndCapture一起使用。

在所有当前在流中排队的项目完成后，在主控端添加一个回调函数。每个cudaStreamAddCallback调用，回调函数将精确执行一次。该回调函数会阻塞流中的后续工作，直到它完成。

回调可能会返回cudaSuccess或错误代码。如果发生设备错误，所有后续执行的回调都将收到相应的cudaError_t。

回调函数不得进行任何CUDA API调用。尝试使用CUDA API可能导致cudaErrorNotPermitted错误。回调函数不得执行任何可能依赖于未完成设备工作或其他未被强制要求优先运行的回调函数的同步操作。没有强制顺序要求的回调函数（在独立流中）将以未定义的顺序执行，并可能被串行化。

就统一内存管理而言，回调执行提供了以下保证：

回调流在回调期间被视为空闲状态。因此，例如，回调可以始终使用附加到回调流的内存。
回调函数的开始执行效果等同于在回调之前立即同步同一流中记录的事件。因此，它会同步在回调之前已被"连接"的流。
在所有前置回调执行完毕之前，向任何流添加设备工作都不会使该流变为活跃状态。因此，举例来说，如果一个回调已通过事件正确排序，即使另一个流已添加了工作，该回调仍可能使用全局附加内存。
回调的完成不会使流变为活动状态，除非如上所述。如果没有后续的设备工作，回调流将保持空闲状态，并且在连续的回调之间如果没有设备工作，也将保持空闲。因此，例如，可以通过在流结束时从回调发出信号来完成流同步。

Note:

该函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaStreamQuery, cudaStreamSynchronize, cudaStreamWaitEvent, cudaStreamDestroy, cudaMallocManaged, cudaStreamAttachMemAsync, cudaLaunchHostFunc, cuStreamAddCallback

__host__ cudaError_t cudaStreamAttachMemAsync ( cudaStream_t stream, void* devPtr, size_t length = 0, unsigned int flags = cudaMemAttachSingle )

异步地将内存附加到流。

参数

stream: - Stream in which to enqueue the attach operation
devPtr: - Pointer to memory (must be a pointer to managed memory or to a valid host-accessible region of system-allocated memory)
length: - Length of memory (defaults to zero)
flags: - Must be one of cudaMemAttachGlobal, cudaMemAttachHost or cudaMemAttachSingle (defaults to cudaMemAttachSingle)

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

在stream中排队一个操作，用于指定从devPtr开始、长度为length字节的内存与流的关联。此函数是一个流顺序操作，意味着它依赖于流中先前的工作，并且只有在流中先前的工作完成后才会生效。任何先前的关联都会被自动替换。

devPtr 必须指向以下类型的内存之一：

使用__managed__关键字声明的托管内存或通过cudaMallocManaged分配的托管内存。
一个有效的、主机可访问的系统分配可分页内存区域。只有当与流关联的设备报告设备属性cudaDevAttrPageableMemoryAccess为非零值时，才能指定此类内存。

对于托管分配，length必须为零或整个分配的大小。两者都表示正在更改整个分配的流关联。目前，无法更改托管分配部分区域的流关联。

对于可分页的内存分配，length必须是非零值。

流关联通过flags参数指定，该参数必须是cudaMemAttachGlobal、cudaMemAttachHost或cudaMemAttachSingle之一。flags的默认值为cudaMemAttachSingle。如果指定了cudaMemAttachGlobal标志，则任何设备上的任何流都可以访问该内存。如果指定了cudaMemAttachHost标志，程序保证不会从设备属性cudaDevAttrConcurrentManagedAccess值为零的设备上的任何流访问该设备上的内存。如果指定了cudaMemAttachSingle标志且stream关联的设备其设备属性cudaDevAttrConcurrentManagedAccess值为零，程序保证仅会通过stream访问该设备上的内存。将内存单独附加到NULL流是非法的，因为NULL流是虚拟全局流而非特定流。这种情况下将返回错误。

当内存与单个流关联时，只要stream中的所有操作已完成，无论其他流是否处于活动状态，统一内存系统都将允许CPU访问此内存区域。实际上，这将活动GPU对托管内存区域的独占所有权限制为按流活动，而非整个GPU活动。

从未关联的流访问设备内存将产生未定义的结果。统一内存系统不会执行错误检查，以确保在其他流中启动的内核不会访问此区域。

程序有责任通过事件、同步或其他方式对cudaStreamAttachMemAsync的调用进行排序，以确保始终合法访问内存。对于所有跟随流关联更改的内核，数据可见性和一致性将相应更改。

如果在数据与stream关联期间该流被销毁，关联关系将被解除，分配将恢复为cudaMallocManaged指定的默认可见性。对于__managed__变量，默认关联始终是cudaMemAttachGlobal。请注意，销毁流是一个异步操作，因此，在流中的所有工作完成之前，不会发生默认关联的更改。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaStreamWaitEvent, cudaStreamSynchronize, cudaStreamAddCallback, cudaStreamDestroy, cudaMallocManaged, cuStreamAttachMemAsync

__host__ cudaError_t cudaStreamBeginCapture ( cudaStream_t stream, cudaStreamCaptureMode mode )

在流上开始图形捕获。

参数

stream: - Stream in which to initiate capture
mode: - Controls the interaction of this capture sequence with other API calls that are potentially unsafe. For more details see cudaThreadExchangeStreamCaptureMode.

cudaSuccess, cudaErrorInvalidValue

描述

在stream上开始图形捕获。当流处于捕获模式时，所有推入该流的操作将不会被执行，而是会被捕获到一个图形中，该图形将通过cudaStreamEndCapture返回。如果stream是cudaStreamLegacy，则可能无法启动捕获。捕获必须在启动它的同一流上结束，并且只有在流尚未处于捕获模式时才能启动。可以通过cudaStreamIsCapturing查询捕获模式。可以通过cudaStreamGetCaptureInfo查询表示捕获序列的唯一ID。

如果mode不是cudaStreamCaptureModeRelaxed，则必须从同一线程对此流调用cudaStreamEndCapture。

Note:

使用此API捕获的内核不得使用纹理和表面引用。通过任何纹理或表面引用进行读写都是未定义行为。此限制不适用于纹理和表面对象。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamCreate, cudaStreamIsCapturing, cudaStreamEndCapture, cudaThreadExchangeStreamCaptureMode

__host__ cudaError_t cudaStreamBeginCaptureToGraph ( cudaStream_t stream, cudaGraph_t graph, const cudaGraphNode_t* dependencies, const cudaGraphEdgeData* dependencyData, size_t numDependencies, cudaStreamCaptureMode mode )

在现有图上开始流式图的捕获。

参数

stream: - Stream in which to initiate capture.
graph: - Graph to capture into.
dependencies: - Dependencies of the first node captured in the stream. Can be NULL if numDependencies is 0.
dependencyData: - Optional array of data associated with each dependency.
numDependencies: - Number of dependencies.
mode: - Controls the interaction of this capture sequence with other API calls that are potentially unsafe. For more details see cudaThreadExchangeStreamCaptureMode.

cudaSuccess, cudaErrorInvalidValue

描述

在stream上开始图形捕获。当流处于捕获模式时，所有推入流的操作都不会被执行，而是会被捕获到graph中，该图将通过cudaStreamEndCapture返回。

如果stream是cudaStreamLegacy，则可能无法启动捕获。捕获必须在启动它的同一流上结束，并且只有在流尚未处于捕获模式时才能启动。可以通过cudaStreamIsCapturing查询捕获模式。可以通过cudaStreamGetCaptureInfo查询表示捕获序列的唯一ID。

如果mode不是cudaStreamCaptureModeRelaxed，则必须从同一线程在此流上调用cudaStreamEndCapture。

Note:

通过此API捕获的内核不得使用纹理和表面引用。通过任何纹理或表面引用进行读写都是未定义行为。此限制不适用于纹理和表面对象。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamCreate, cudaStreamIsCapturing, cudaStreamEndCapture, cudaThreadExchangeStreamCaptureMode

__host__ cudaError_t cudaStreamCopyAttributes ( cudaStream_t dst, cudaStream_t src )

将属性从源流复制到目标流。

参数

dst: Destination stream
src: Source stream For attributes see cudaStreamAttrID

cudaSuccess, cudaErrorNotSupported

描述

将属性从源流src复制到目标流dst。两个流必须具有相同的上下文。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaAccessPolicyWindow

__host__ cudaError_t cudaStreamCreate ( cudaStream_t* pStream )

创建一个异步流。

参数

pStream: - Pointer to new stream identifier

cudaSuccess, cudaErrorInvalidValue

描述

在当前调用主机线程的上下文中创建一个新的异步流。如果调用主机线程没有当前上下文，则会选择一个设备的主上下文，使其成为调用线程的当前上下文，并在创建流之前进行初始化。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreateWithPriority, cudaStreamCreateWithFlags, cudaStreamGetPriority, cudaStreamGetFlags, cudaStreamGetDevice, cudaStreamQuery, cudaStreamSynchronize, cudaStreamWaitEvent, cudaStreamAddCallback, cudaSetDevice, cudaStreamDestroy, cuStreamCreate

__host__ __device__ cudaError_t cudaStreamCreateWithFlags ( cudaStream_t* pStream, unsigned int flags )

创建一个异步流。

参数

pStream: - Pointer to new stream identifier
flags: - Parameters for stream creation

cudaSuccess, cudaErrorInvalidValue

描述

在当前调用主机线程的上下文中创建一个新的异步流。如果调用主机线程没有当前上下文，则会选择一个设备的主上下文，使其成为调用线程的当前上下文，并在创建流之前进行初始化。flags参数决定了流的行为。flags的有效值为

cudaStreamDefault: 默认流创建标志。
cudaStreamNonBlocking: 指定在创建的流中运行的工作可以与流0（NULL流）中的工作并发运行，并且创建的流不应与流0执行任何隐式同步。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithPriority, cudaStreamGetFlags, cudaStreamGetDevice, cudaStreamQuery, cudaStreamSynchronize, cudaStreamWaitEvent, cudaStreamAddCallback, cudaSetDevice, cudaStreamDestroy, cuStreamCreate

__host__ cudaError_t cudaStreamCreateWithPriority ( cudaStream_t* pStream, unsigned int flags, int priority )

创建一个具有指定优先级的异步流。

参数

pStream: - Pointer to new stream identifier
flags: - Flags for stream creation. See cudaStreamCreateWithFlags for a list of valid flags that can be passed
priority: - Priority of the stream. Lower numbers represent higher priorities. See cudaDeviceGetStreamPriorityRange for more information about the meaningful stream priorities that can be passed.

cudaSuccess, cudaErrorInvalidValue

描述

创建一个具有指定优先级的流，并在pStream中返回其句柄。该流将在调用主机线程当前的上下文中创建。如果调用主机线程没有当前上下文，则会选择一个设备的主上下文，使其成为调用线程的当前上下文，并在其上初始化后再创建流。这会影响流中工作的调度优先级。优先级提供了一种提示，以便在可能的情况下优先运行优先级更高的工作，但不会抢占已经在运行的工作，也不会对执行顺序提供任何其他功能保证。

priority遵循数值越小优先级越高的约定。'0'表示默认优先级。有效的数值优先级范围可通过cudaDeviceGetStreamPriorityRange查询。如果指定的优先级超出cudaDeviceGetStreamPriorityRange返回的数值范围，系统会自动将其调整为该范围内的最小值或最大值。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
仅支持计算能力3.5或更高版本的GPU上的流优先级。
在当前实现中，只有优先级流中启动的计算内核会受到流优先级的影响。流优先级对主机到设备和设备到主机的内存操作没有影响。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaDeviceGetStreamPriorityRange, cudaStreamGetPriority, cudaStreamQuery, cudaStreamWaitEvent, cudaStreamAddCallback, cudaStreamSynchronize, cudaSetDevice, cudaStreamDestroy, cuStreamCreateWithPriority

__host__ __device__ cudaError_t cudaStreamDestroy ( cudaStream_t stream )

销毁并清理一个异步流。

参数

stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

销毁并清理由stream指定的异步流。

如果在调用cudaStreamDestroy()时设备仍在流stream中执行工作，该函数将立即返回，并且与stream关联的资源将在设备完成stream中的所有工作后自动释放。

Note:

该函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
在此调用后使用该句柄将导致未定义行为。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaStreamQuery, cudaStreamWaitEvent, cudaStreamSynchronize, cudaStreamAddCallback, cuStreamDestroy

__host__ cudaError_t cudaStreamEndCapture ( cudaStream_t stream, cudaGraph_t* pGraph )

结束在流上的捕获，返回捕获的图。

参数

stream: - Stream to query
pGraph: - The captured graph

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureWrongThread

描述

在stream上结束捕获，通过pGraph返回捕获的计算图。必须事先通过调用cudaStreamBeginCapture在stream上启动捕获。如果由于违反流捕获规则导致捕获失效，则将返回NULL图。

如果cudaStreamBeginCapture的mode参数不是cudaStreamCaptureModeRelaxed，则此调用必须与cudaStreamBeginCapture来自同一线程。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamCreate, cudaStreamBeginCapture, cudaStreamIsCapturing, cudaGraphDestroy

__host__ cudaError_t cudaStreamGetAttribute ( cudaStream_t hStream, cudaStreamAttrID attr, cudaStreamAttrValue* value_out )

查询流属性。

参数

hStream
attr
value_out

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

从hStream查询属性attr，并将其存储在value_out对应的成员中。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaAccessPolicyWindow

__host__ cudaError_t cudaStreamGetCaptureInfo ( cudaStream_t stream, cudaStreamCaptureStatus ** captureStatus_out, unsigned long long* id_out = 0, cudaGraph_t* graph_out = 0, const cudaGraphNode_t** dependencies_out = 0, size_t* numDependencies_out = 0 )

查询流的捕获状态。

参数

stream: - The stream to query
captureStatus_out: - Location to return the capture status of the stream; required
id_out: - Optional location to return an id for the capture sequence, which is unique over the lifetime of the process
graph_out: - Optional location to return the graph being captured into. All operations other than destroy and node removal are permitted on the graph while the capture sequence is in progress. This API does not transfer ownership of the graph, which is transferred or destroyed at cudaStreamEndCapture. Note that the graph handle may be invalidated before end of capture for certain errors. Nodes that are or become unreachable from the original stream at cudaStreamEndCapture due to direct actions on the graph do not trigger cudaErrorStreamCaptureUnjoined.
dependencies_out: - Optional location to store a pointer to an array of nodes. The next node to be captured in the stream will depend on this set of nodes, absent operations such as event wait which modify this set. The array pointer is valid until the next API call which operates on the stream or until the capture is terminated. The node handles may be copied out and are valid until they or the graph is destroyed. The driver-owned array may also be passed directly to APIs that operate on the graph (not the stream) without copying.
numDependencies_out: - Optional location to store the size of the array returned in dependencies_out.

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureImplicit

描述

查询与流捕获相关的流状态。

如果在未使用cudaStreamNonBlocking创建的流正在捕获时调用cudaStreamLegacy（"空流"），则返回cudaErrorStreamCaptureImplicit。

只有在以下两个条件同时满足时，才会返回有效数据（捕获状态除外）：

调用返回 cudaSuccess
返回的捕获状态是 cudaStreamCaptureStatusActive

Note:

图形对象不是线程安全的。更多信息。
请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamGetCaptureInfo_v3, cudaStreamBeginCapture, cudaStreamIsCapturing, cudaStreamUpdateCaptureDependencies

__host__ cudaError_t cudaStreamGetCaptureInfo_v3 ( cudaStream_t stream, cudaStreamCaptureStatus ** captureStatus_out, unsigned long long* id_out = 0, cudaGraph_t* graph_out = 0, const cudaGraphNode_t** dependencies_out = 0, const cudaGraphEdgeData** edgeData_out = 0, size_t* numDependencies_out = 0 )

查询流的捕获状态（12.3+版本）。

参数

stream: - The stream to query
captureStatus_out: - Location to return the capture status of the stream; required
id_out: - Optional location to return an id for the capture sequence, which is unique over the lifetime of the process
graph_out: - Optional location to return the graph being captured into. All operations other than destroy and node removal are permitted on the graph while the capture sequence is in progress. This API does not transfer ownership of the graph, which is transferred or destroyed at cudaStreamEndCapture. Note that the graph handle may be invalidated before end of capture for certain errors. Nodes that are or become unreachable from the original stream at cudaStreamEndCapture due to direct actions on the graph do not trigger cudaErrorStreamCaptureUnjoined.
dependencies_out: - Optional location to store a pointer to an array of nodes. The next node to be captured in the stream will depend on this set of nodes, absent operations such as event wait which modify this set. The array pointer is valid until the next API call which operates on the stream or until the capture is terminated. The node handles may be copied out and are valid until they or the graph is destroyed. The driver-owned array may also be passed directly to APIs that operate on the graph (not the stream) without copying.
edgeData_out: - Optional location to store a pointer to an array of graph edge data. This array parallels dependencies_out; the next node to be added has an edge to dependencies_out[i] with annotation edgeData_out[i] for each i. The array pointer is valid until the next API call which operates on the stream or until the capture is terminated.
numDependencies_out: - Optional location to store the size of the array returned in dependencies_out.

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureImplicit, cudaErrorLossyQuery

描述

查询与流捕获相关的流状态。

如果在未使用cudaStreamNonBlocking创建的流正在捕获时调用cudaStreamLegacy（"空流"），则返回cudaErrorStreamCaptureImplicit。

只有在以下两个条件同时满足时，才会返回有效数据（捕获状态除外）：

调用返回 cudaSuccess
返回的捕获状态是 cudaStreamCaptureStatusActive

如果edgeData_out非空，则dependencies_out也必须非空。如果dependencies_out非空而edgeData_out为空，但当前流依赖关系中存在一个或多个非零边数据时，调用将返回cudaErrorLossyQuery。

Note:

图形对象不是线程安全的。更多信息。
请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamBeginCapture, cudaStreamIsCapturing, cudaStreamUpdateCaptureDependencies

__host__ cudaError_t cudaStreamGetDevice ( cudaStream_t hStream, int* device )

查询流的设备。

参数

hStream: - Handle to the stream to be queried
device: - Returns the device to which the stream belongs

cudaSuccess, cudaErrorInvalidValue, cudaErrorDeviceUnavailable,

描述

返回*device中流所在的设备。

Note:

该函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，cudaErrorNotPermitted可能会（但不保证）作为诊断信息返回。

另请参阅：

cudaSetDevice, cudaGetDevice, cudaStreamCreate, cudaStreamGetPriority, cudaStreamGetFlags, cuStreamGetId

__host__ cudaError_t cudaStreamGetFlags ( cudaStream_t hStream, unsigned int* flags )

查询流的标志位。

参数

hStream: - Handle to the stream to be queried
flags: - Pointer to an unsigned integer in which the stream's flags are returned

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

查询流的标志。标志将在flags中返回。有关有效标志列表，请参阅cudaStreamCreateWithFlags。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreateWithPriority, cudaStreamCreateWithFlags, cudaStreamGetPriority, cudaStreamGetDevice, cuStreamGetFlags

__host__ cudaError_t cudaStreamGetId ( cudaStream_t hStream, unsigned long long* streamId )

查询流的ID。

参数

hStream: - Handle to the stream to be queried
streamId: - Pointer to an unsigned long long in which the stream Id is returned

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

查询流的ID。该ID通过streamId返回。该ID在程序运行期间保持唯一。

流句柄 hStream 可以指向以下任意一种情况：

通过任何CUDA运行时API（如cudaStreamCreate、cudaStreamCreateWithFlags和cudaStreamCreateWithPriority）或其驱动程序API等效项（如cuStreamCreate或cuStreamCreateWithPriority）创建的流。传递无效句柄将导致未定义行为。
任何特殊流，例如NULL流、cudaStreamLegacy和cudaStreamPerThread。驱动API对应的等效流NULL、CU_STREAM_LEGACY和CU_STREAM_PER_THREAD也同样被接受。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreateWithPriority, cudaStreamCreateWithFlags, cudaStreamGetPriority, cudaStreamGetFlags, cuStreamGetId

__host__ cudaError_t cudaStreamGetPriority ( cudaStream_t hStream, int* priority )

查询流的优先级。

参数

hStream: - Handle to the stream to be queried
priority: - Pointer to a signed integer in which the stream's priority is returned

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

查询流的优先级。优先级将在priority中返回。请注意，如果流创建时使用的优先级超出了cudaDeviceGetStreamPriorityRange返回的有效数值范围，此函数将返回经过限幅处理的优先级。有关优先级限幅的详细信息，请参阅cudaStreamCreateWithPriority。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreateWithPriority, cudaDeviceGetStreamPriorityRange, cudaStreamGetFlags, cudaStreamGetDevice, cuStreamGetPriority

__host__ cudaError_t cudaStreamIsCapturing ( cudaStream_t stream, cudaStreamCaptureStatus ** pCaptureStatus )

返回流的捕获状态。

参数

stream: - Stream to query
pCaptureStatus: - Returns the stream's capture status

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureImplicit

描述

通过pCaptureStatus返回stream的捕获状态。成功调用后，*pCaptureStatus将包含以下值之一：

cudaStreamCaptureStatusNone: 该流未处于捕获状态。
cudaStreamCaptureStatusActive: 该流正在捕获中。
cudaStreamCaptureStatusInvalidated: 流正在进行捕获操作，但发生错误导致捕获序列失效。必须在该流上调用cudaStreamEndCapture来终止捕获序列，才能继续使用stream。

请注意，如果在同一设备上的阻塞流正在捕获时，对cudaStreamLegacy（"空流"）调用此函数，它将返回cudaErrorStreamCaptureImplicit，并且调用后*pCaptureStatus的状态未指定。阻塞流的捕获操作不会因此失效。

当一个阻塞流正在进行捕获时，传统流将处于不可用状态，直到阻塞流捕获终止。传统流不支持流捕获功能，但尝试使用会产生对捕获流的隐式依赖。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamCreate, cudaStreamBeginCapture, cudaStreamEndCapture

__host__ cudaError_t cudaStreamQuery ( cudaStream_t stream )

查询异步流的完成状态。

参数

stream: - Stream identifier

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidResourceHandle

描述

如果stream中的所有操作都已完成，则返回cudaSuccess；如果未完成，则返回cudaErrorNotReady。

就统一内存管理而言，返回值为cudaSuccess等同于调用了cudaStreamSynchronize()函数。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaStreamWaitEvent, cudaStreamSynchronize, cudaStreamAddCallback, cudaStreamDestroy, cuStreamQuery

__host__ cudaError_t cudaStreamSetAttribute ( cudaStream_t hStream, cudaStreamAttrID attr, const cudaStreamAttrValue* value )

设置流属性。

参数

hStream
attr
value

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

将value对应的属性设置到hStream的attr属性上。更新后的属性将应用于后续提交到该流的工作，但不会影响之前已提交的工作。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaAccessPolicyWindow

__host__ cudaError_t cudaStreamSynchronize ( cudaStream_t stream )

等待流任务完成。

参数

stream: - Stream identifier

cudaSuccess, cudaErrorInvalidResourceHandle

描述

阻塞直到stream完成所有操作。如果为此设备设置了cudaDeviceScheduleBlockingSync标志，主机线程将阻塞直到流完成其所有任务。

Note:

该函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaStreamQuery, cudaStreamWaitEvent, cudaStreamAddCallback, cudaStreamDestroy, cuStreamSynchronize

__host__ cudaError_t cudaStreamUpdateCaptureDependencies ( cudaStream_t stream, cudaGraphNode_t* dependencies, size_t numDependencies, unsigned int flags = 0 )

更新捕获流中的依赖项集合（11.3+版本）。

参数

stream: - The stream to update
dependencies: - The set of dependencies to add
numDependencies: - The size of the dependencies array
flags: - See above

cudaSuccess, cudaErrorInvalidValue, cudaErrorIllegalState

描述

修改捕获流的依赖集。依赖集是指流中下一个被捕获节点所依赖的节点集合。

有效的标志位是cudaStreamAddCaptureDependencies和cudaStreamSetCaptureDependencies。这些标志控制传递给API的集合是追加到现有集合还是替换它。当flags值为0时，默认采用cudaStreamAddCaptureDependencies行为。

通过此API从依赖集中移除的节点，如果在cudaStreamEndCapture时无法从流中访问，则不会导致cudaErrorStreamCaptureUnjoined错误。

如果流未处于捕获状态，则返回 cudaErrorIllegalState。

该API是CUDA 11.3新增的。需要兼容CUDA 11.0及以上小版本驱动的开发者不应使用此API或需提供回退方案。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamBeginCapture, cudaStreamGetCaptureInfo,

__host__ cudaError_t cudaStreamUpdateCaptureDependencies_v2 ( cudaStream_t stream, cudaGraphNode_t* dependencies, const cudaGraphEdgeData* dependencyData, size_t numDependencies, unsigned int flags = 0 )

更新捕获流中的依赖项集合（12.3+版本）。

参数

stream: - The stream to update
dependencies: - The set of dependencies to add
dependencyData: - Optional array of data associated with each dependency.
numDependencies: - The size of the dependencies array
flags: - See above

cudaSuccess, cudaErrorInvalidValue, cudaErrorIllegalState

描述

修改捕获流的依赖集。依赖集是指流中下一个被捕获节点所依赖的节点集合。

有效的标志位包括cudaStreamAddCaptureDependencies和cudaStreamSetCaptureDependencies。这些标志控制传递给API的集合是追加到现有集合还是替换它。当标志值为0时，默认采用cudaStreamAddCaptureDependencies行为。

通过此API从依赖集中移除的节点，如果在cudaStreamEndCapture时无法从流中访问，则不会导致cudaErrorStreamCaptureUnjoined错误。

如果流未处于捕获状态，则返回 cudaErrorIllegalState。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamBeginCapture, cudaStreamGetCaptureInfo,

__host__ __device__ cudaError_t cudaStreamWaitEvent ( cudaStream_t stream, cudaEvent_t event, unsigned int flags = 0 )

让计算流等待某个事件。

参数

stream: - Stream to wait
event: - Event to wait on
flags: - Parameters for the operation(See above)

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

使所有后续提交到stream的工作等待event中捕获的所有工作完成。关于事件捕获内容的详细信息，请参阅cudaEventRecord()。在适用情况下，设备将高效执行此同步操作。 event可以来自与stream不同的设备。

标志包括：

cudaEventWaitDefault: 默认事件创建标志。
cudaEventWaitExternal: 在执行流捕获时，事件在图中被捕获为外部事件节点。

Note:

该函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部CUDA RT状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaStreamCreate, cudaStreamCreateWithFlags, cudaStreamQuery, cudaStreamSynchronize, cudaStreamAddCallback, cudaStreamDestroy, cuStreamWaitEvent

__host__ cudaError_t cudaThreadExchangeStreamCaptureMode ( cudaStreamCaptureMode ** mode )

交换线程的流捕获交互模式。

参数

mode: - Pointer to mode value to swap with the current mode

cudaSuccess, cudaErrorInvalidValue

描述

将调用线程的流捕获交互模式设置为*mode中包含的值，并用线程之前的模式覆盖*mode。为了确保跨函数或模块边界的行为确定性，建议调用者以压入-弹出的方式使用此API：

‎     cudaStreamCaptureMode mode = desiredMode;
           cudaThreadExchangeStreamCaptureMode(&mode);
           ...
           cudaThreadExchangeStreamCaptureMode(&mode); // restore previous mode

在流捕获期间（参见cudaStreamBeginCapture），某些操作（例如调用cudaMalloc）可能不安全。对于cudaMalloc的情况，该操作不会异步加入流队列，也不会被流捕获机制观察到。因此，如果通过cudaStreamBeginCapture捕获的操作序列依赖于每次启动图时重新执行分配操作，那么所捕获的图将是无效的。

因此，流捕获对在cudaStreamBeginCapture-cudaStreamEndCapture序列内部或并发执行的API调用施加了限制。此行为可通过该API以及传递给cudaStreamBeginCapture的标志进行控制。

线程的模式为以下之一：

cudaStreamCaptureModeGlobal: 这是默认模式。如果当前线程存在一个未以cudaStreamCaptureModeRelaxed模式通过cuStreamBeginCapture启动的捕获序列，或者任何其他线程存在以cudaStreamCaptureModeGlobal启动的并发捕获序列，则该线程将被禁止调用可能存在安全隐患的API接口。
cudaStreamCaptureModeThreadLocal: 如果当前线程有一个未以cudaStreamCaptureModeRelaxed启动的正在进行的捕获序列，则禁止该线程进行潜在不安全的API调用。其他线程中的并发捕获序列将被忽略。
cudaStreamCaptureModeRelaxed: 不禁止本地线程可能进行的不安全API调用。需注意，线程仍被禁止执行必然与流捕获冲突的API调用，例如尝试对捕获序列内最后记录的事件执行cudaEventQuery。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cudaStreamBeginCapture