CUDA 运行时 API :: CUDA 工具包文档

6.5. 流管理

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

类型定义

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

函数

__host__ cudaError_t cudaCtxResetPersistingL2Cache ( void ): 将缓存中的所有持久化行重置为正常状态。
__host__ cudaError_t cudaStreamAddCallback ( cudaStream_t stream, cudaStreamCallback_t callback, void* userData, unsigned int flags ): 向计算流添加回调。
__host__ cudaError_t cudaStreamAttachMemAsync ( cudaStream_t stream, void* devPtr, size_t length = 0, unsigned int flags = cudaMemAttachSingle ): 异步地将内存附加到流。
__host__ cudaError_t cudaStreamBeginCapture ( cudaStream_t stream, cudaStreamCaptureMode mode ): 在流上开始图形捕获。
__host__ cudaError_t cudaStreamBeginCaptureToGraph ( cudaStream_t stream, cudaGraph_t graph, const cudaGraphNode_t* dependencies, const cudaGraphEdgeData* dependencyData, size_t numDependencies, cudaStreamCaptureMode mode ): 在流上开始图形捕获到现有图形。
__host__ cudaError_t cudaStreamCopyAttributes ( cudaStream_t dst, cudaStream_t src ): 将属性从源流复制到目标流。
__host__ cudaError_t cudaStreamCreate ( cudaStream_t* pStream ): 创建一个异步流。
__host__ __device__ cudaError_t cudaStreamCreateWithFlags ( cudaStream_t* pStream, unsigned int flags ): 创建一个异步流。
__host__ cudaError_t cudaStreamCreateWithPriority ( cudaStream_t* pStream, unsigned int flags, int priority ): 创建具有指定优先级的异步流。
__host__ __device__ cudaError_t cudaStreamDestroy ( cudaStream_t stream ): 销毁并清理异步流。
__host__ cudaError_t cudaStreamEndCapture ( cudaStream_t stream, cudaGraph_t* pGraph ): 结束流上的捕获，返回捕获的图形。
__host__ cudaError_t cudaStreamGetAttribute ( cudaStream_t hStream, cudaStreamAttrID attr, cudaStreamAttrValue* value_out ): 查询流属性。
__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 ): 查询流的捕获状态。
__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+) 。
__host__ cudaError_t cudaStreamGetDevice ( cudaStream_t hStream, int* device ): 查询流的设备。
__host__ cudaError_t cudaStreamGetFlags ( cudaStream_t hStream, unsigned int* flags ): 查询流的标志。
__host__ cudaError_t cudaStreamGetId ( cudaStream_t hStream, unsigned long long* streamId ): 查询流的 Id。
__host__ cudaError_t cudaStreamGetPriority ( cudaStream_t hStream, int* priority ): 查询流的优先级。
__host__ cudaError_t cudaStreamIsCapturing ( cudaStream_t stream, cudaStreamCaptureStatus ** pCaptureStatus ): 返回流的捕获状态。
__host__ cudaError_t cudaStreamQuery ( cudaStream_t stream ): 查询异步流的完成状态。
__host__ cudaError_t cudaStreamSetAttribute ( cudaStream_t hStream, cudaStreamAttrID attr, const cudaStreamAttrValue* value ): 设置流属性。
__host__ cudaError_t cudaStreamSynchronize ( cudaStream_t stream ): 等待流任务完成。
__host__ cudaError_t cudaStreamUpdateCaptureDependencies ( cudaStream_t stream, cudaGraphNode_t* dependencies, size_t numDependencies, unsigned int flags = 0 ): 更新捕获流中的依赖项集 (11.3+) 。
__host__ cudaError_t cudaStreamUpdateCaptureDependencies_v2 ( cudaStream_t stream, cudaGraphNode_t* dependencies, const cudaGraphEdgeData* dependencyData, size_t numDependencies, unsigned int flags = 0 ): 更新捕获流中的依赖项集 (12.3+) 。
__host__ __device__ cudaError_t cudaStreamWaitEvent ( cudaStream_t stream, cudaEvent_t event, unsigned int flags = 0 ): 使计算流等待事件。
__host__ cudaError_t cudaThreadExchangeStreamCaptureMode ( cudaStreamCaptureMode ** mode ): 交换线程的流捕获交互模式。

类型定义

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

函数

__host__ cudaError_t cudaCtxResetPersistingL2Cache ( void )

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

返回值

cudaSuccess,

描述

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

注意

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

另请参阅

cudaAccessPolicyWindow

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

向计算流添加回调。

参数

stream: - 要向其添加回调的流
callback: - 先前流操作完成后要调用的函数
userData: - 要传递给回调函数的用户指定数据
flags: - 保留以供将来使用，必须为 0

返回值

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorInvalidValue, cudaErrorNotSupported

描述

注意

此函数计划最终弃用和删除。如果您不要求在设备错误的情况下执行回调，请考虑使用 cudaLaunchHostFunc。此外，与 cudaStreamBeginCapture 和 cudaStreamEndCapture 不同，此函数不支持 cudaLaunchHostFunc。

添加一个回调，以便在流中所有当前排队的项目都完成后在主机上调用。对于每个 cudaStreamAddCallback 调用，将精确执行一次回调。回调将阻止流中后续的工作，直到它完成。

回调可以传递 cudaSuccess 或错误代码。如果发生设备错误，所有后续执行的回调都将收到适当的 cudaError_t。

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

为了统一内存的目的，回调执行做出了一些保证

在回调期间，回调流被认为是空闲的。因此，例如，回调始终可以使用附加到回调流的内存。
回调执行的开始与同步在回调之前立即在同一流中记录的事件具有相同的效果。因此，它同步了在回调之前已“加入”的流。
向任何流添加设备工作不会使流变为活动状态，直到所有先前的回调都已执行完毕。因此，例如，即使已向另一个流添加了工作，回调也可能使用全局附加内存，如果它已通过事件正确排序。
完成回调不会导致流变为活动状态，除非如上所述。如果回调后没有设备工作，则回调流将保持空闲状态，并且在没有设备工作的情况下，在连续回调之间将保持空闲状态。因此，例如，流同步可以通过从流末尾的回调发出信号来完成。

注意

此函数使用标准默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 在其中排队附加操作的流
devPtr: - 指向内存的指针（必须是指向托管内存或系统分配内存的有效主机可访问区域的指针）
length: - 内存长度（默认为零）
flags: - 必须是 cudaMemAttachGlobal、cudaMemAttachHost 或 cudaMemAttachSingle 之一（默认为 cudaMemAttachSingle）

返回值

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

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

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

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

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

对于可分页分配，length必须为非零值。

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

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

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

程序有责任通过事件、同步或其他方式对 cudaStreamAttachMemAsync 的调用进行排序，以确保在任何时候都能合法访问内存。数据可见性和一致性将针对所有遵循流关联更改的内核进行适当更改。

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

注意

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 在其中启动捕获的流
mode: - 控制此捕获序列与可能不安全的其他 API 调用的交互。有关更多详细信息，请参阅 cudaThreadExchangeStreamCaptureMode。

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

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

注意

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

注意

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

另请参阅

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: - 在其中启动捕获的流。
graph: - 要捕获到的图形。
dependencies: - 流中捕获的第一个节点的依赖项。如果 numDependencies 为 0，则可以为 NULL。
dependencyData: - 与每个依赖项关联的可选数据数组。
numDependencies: - 依赖项的数量。
mode: - 控制此捕获序列与可能不安全的其他 API 调用的交互。有关更多详细信息，请参阅 cudaThreadExchangeStreamCaptureMode。

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

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

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

注意

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

注意

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

另请参阅

cudaStreamCreate, cudaStreamIsCapturing, cudaStreamEndCapture, cudaThreadExchangeStreamCaptureMode

__host__ cudaError_t cudaStreamCopyAttributes ( cudaStream_t dst, cudaStream_t src )

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

参数

dst: 目标流
src: 源流。有关属性，请参阅 cudaStreamAttrID

返回值

cudaSuccess, cudaErrorNotSupported

描述

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

注意

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

另请参阅

cudaAccessPolicyWindow

__host__ cudaError_t cudaStreamCreate ( cudaStream_t* pStream )

创建一个异步流。

参数

pStream: - 指向新流标识符的指针

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

注意

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 指向新流标识符的指针
flags: - 流创建的参数

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

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

注意

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 指向新流标识符的指针
flags: - 流创建的标志。有关可以传递的有效标志列表，请参阅 cudaStreamCreateWithFlags
priority: - 流的优先级。较小的数字表示较高的优先级。有关可以传递的有意义的流优先级的更多信息，请参阅 cudaDeviceGetStreamPriorityRange。

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

priority遵循一个约定，其中较小的数字表示较高的优先级。 “0”表示默认优先级。可以使用 cudaDeviceGetStreamPriorityRange 查询有意义的数值优先级的范围。如果指定的优先级超出 cudaDeviceGetStreamPriorityRange 返回的数值范围，它将自动被钳制到范围内的最低或最高数字。

注意

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 流标识符

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

销毁并清理由stream.

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

注意

此函数使用标准默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 要查询的流
pGraph: - 捕获的图形

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureWrongThread

描述

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

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

注意

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

另请参阅

cudaStreamCreate, cudaStreamBeginCapture, cudaStreamIsCapturing, cudaGraphDestroy

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

查询流属性。

参数

hStream
attr
value_out

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

查询来自attr的属性hStream并将其存储在的相应成员中value_out.

注意

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

另请参阅

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: - 要查询的流
captureStatus_out: - 用于返回流的捕获状态的位置；必需
id_out: - 用于返回捕获序列 ID 的可选位置，该 ID 在进程的生命周期内是唯一的
graph_out: - 用于返回正在捕获到的图形的可选位置。在捕获序列正在进行时，允许对图形执行除销毁和节点删除之外的所有操作。此 API 不会转移图形的所有权，该所有权将在 cudaStreamEndCapture 处转移或销毁。请注意，对于某些错误，图形句柄可能会在捕获结束之前失效。由于直接对图形执行操作而导致在 cudaStreamEndCapture 处从原始流不可达或变为不可达的节点不会触发 cudaErrorStreamCaptureUnjoined。
dependencies_out: - 用于存储指向节点数组的指针的可选位置。要在流中捕获的下一个节点将依赖于这组节点，除非事件等待等修改此组的操作。数组指针在对流进行操作的下一个 API 调用之前或捕获终止之前有效。节点句柄可以复制出来，并且在节点或图形被销毁之前有效。驱动程序拥有的数组也可以直接传递给对图形 (而不是流) 进行操作的 API，而无需复制。
numDependencies_out: - 用于存储 dependencies_out 中返回的数组大小的可选位置。

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureImplicit

描述

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

如果在 cudaStreamLegacy (“空流”) 上调用，同时使用非 cudaStreamNonBlocking 创建的流正在捕获，则返回 cudaErrorStreamCaptureImplicit。

只有在以下两个条件都为真时，才会返回有效数据(捕获状态除外)

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

注意

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

另请参阅

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: - 要查询的流
captureStatus_out: - 用于返回流的捕获状态的位置；必需
id_out: - 用于返回捕获序列 ID 的可选位置，该 ID 在进程的生命周期内是唯一的
graph_out: - 用于返回正在捕获到的图形的可选位置。在捕获序列正在进行时，允许对图形执行除销毁和节点删除之外的所有操作。此 API 不会转移图形的所有权，该所有权将在 cudaStreamEndCapture 处转移或销毁。请注意，对于某些错误，图形句柄可能会在捕获结束之前失效。由于直接对图形执行操作而导致在 cudaStreamEndCapture 处从原始流不可达或变为不可达的节点不会触发 cudaErrorStreamCaptureUnjoined。
dependencies_out: - 用于存储指向节点数组的指针的可选位置。要在流中捕获的下一个节点将依赖于这组节点，除非事件等待等修改此组的操作。数组指针在对流进行操作的下一个 API 调用之前或捕获终止之前有效。节点句柄可以复制出来，并且在节点或图形被销毁之前有效。驱动程序拥有的数组也可以直接传递给对图形 (而不是流) 进行操作的 API，而无需复制。
edgeData_out: - 可选位置，用于存储指向图边数据数组的指针。此数组与以下项并行：dependencies_out；即将添加的下一个节点具有指向以下项的边：dependencies_out[i] 带有注释edgeData_out[i] 对于每个i。数组指针在对流进行操作的下一个 API 调用之前或捕获终止之前有效。
numDependencies_out: - 用于存储 dependencies_out 中返回的数组大小的可选位置。

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureImplicit, cudaErrorLossyQuery

描述

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

如果在 cudaStreamLegacy (“空流”) 上调用，同时使用非 cudaStreamNonBlocking 创建的流正在捕获，则返回 cudaErrorStreamCaptureImplicit。

只有在以下两个条件都为真时，才会返回有效数据(捕获状态除外)

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

如果edgeData_out为非 NULL，则dependencies_out也必须为非 NULL。如果dependencies_out为非 NULL 且edgeData_out为 NULL，但当前流依赖项中的一个或多个存在非零边数据，则调用将返回 cudaErrorLossyQuery。

注意

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

另请参阅

cudaStreamBeginCapture, cudaStreamIsCapturing, cudaStreamUpdateCaptureDependencies

__host__ cudaError_t cudaStreamGetDevice ( cudaStream_t hStream, int* device )

查询流的设备。

参数

hStream: - 要查询的流的句柄
device: - 返回流所属的设备

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorDeviceUnavailable,

描述

在以下项中返回*device流的设备。

注意

此函数使用标准默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 要查询的流的句柄
flags: - 指向无符号整数的指针，流的标志将在其中返回

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

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

注意

此函数使用标准默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 要查询的流的句柄
streamId: - 指向无符号 long long 的指针，流 ID 将在其中返回

返回值

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。

注意

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

另请参阅

cudaStreamCreateWithPriority, cudaStreamCreateWithFlags, cudaStreamGetPriority, cudaStreamGetFlags, cuStreamGetId

__host__ cudaError_t cudaStreamGetPriority ( cudaStream_t hStream, int* priority )

查询流的优先级。

参数

hStream: - 要查询的流的句柄
priority: - 指向有符号整数的指针，流的优先级将在其中返回

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

查询流的优先级。优先级在以下项中返回priority。请注意，如果流是使用超出 cudaDeviceGetStreamPriorityRange 返回的有意义数值范围之外的优先级创建的，则此函数将返回 clamped 优先级。有关优先级 clamping 的详细信息，请参阅 cudaStreamCreateWithPriority。

注意

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

另请参阅

cudaStreamCreateWithPriority, cudaDeviceGetStreamPriorityRange, cudaStreamGetFlags, cudaStreamGetDevice, cuStreamGetPriority

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

返回流的捕获状态。

参数

stream: - 要查询的流
pCaptureStatus: - 返回流的捕获状态

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorStreamCaptureImplicit

描述

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

cudaStreamCaptureStatusNone：流未捕获。
cudaStreamCaptureStatusActive：流正在捕获。
cudaStreamCaptureStatusInvalidated：流正在捕获，但错误使捕获序列无效。必须在启动捕获序列的流上使用 cudaStreamEndCapture 终止捕获序列，才能继续使用stream.

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

当阻塞流正在捕获时，传统流处于不可用状态，直到阻塞流捕获终止。传统流不支持流捕获，但尝试使用将对捕获流具有隐式依赖性。

注意

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

另请参阅

cudaStreamCreate, cudaStreamBeginCapture, cudaStreamEndCapture

__host__ cudaError_t cudaStreamQuery ( cudaStream_t stream )

查询异步流的完成状态。

参数

stream: - 流标识符

返回值

cudaSuccess, cudaErrorNotReady, cudaErrorInvalidResourceHandle

描述

如果以下项中的所有操作都已完成，则返回 cudaSuccessstream已完成，否则如果未完成，则返回 cudaErrorNotReady。

出于统一内存的目的，cudaSuccess 的返回值等同于调用了 cudaStreamSynchronize()。

注意

此函数使用标准默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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

描述

设置属性attr在hStream从以下项的相应属性value。更新后的属性将应用于随后提交到流的工作。它不会影响先前提交的工作。

注意

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

另请参阅

cudaAccessPolicyWindow

__host__ cudaError_t cudaStreamSynchronize ( cudaStream_t stream )

等待流任务完成。

参数

stream: - 流标识符

返回值

cudaSuccess, cudaErrorInvalidResourceHandle

描述

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

注意

此函数使用标准默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化内部 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: - 要更新的流
dependencies: - 要添加的依赖项集合
numDependencies: - 依赖项数组的大小
flags: - 见上文

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorIllegalState

描述

修改捕获流的依赖项集合。依赖项集合是流中下一个捕获的节点将依赖的节点集合。

有效标志是 cudaStreamAddCaptureDependencies 和 cudaStreamSetCaptureDependencies。这些标志控制传递给 API 的集合是添加到现有集合还是替换现有集合。标志值 0 默认为 cudaStreamAddCaptureDependencies。

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

如果流未捕获，则返回 cudaErrorIllegalState 错误。

此 API 在 CUDA 11.3 中是新增功能。需要在 CUDA 驱动程序的次要版本（到 11.0）之间保持兼容性的开发人员不应使用此 API 或提供回退。

注意

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

另请参阅

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: - 要更新的流
dependencies: - 要添加的依赖项集合
dependencyData: - 与每个依赖项关联的可选数据数组。
numDependencies: - 依赖项数组的大小
flags: - 见上文

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorIllegalState

描述

修改捕获流的依赖项集合。依赖项集合是流中下一个捕获的节点将依赖的节点集合。

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

如果流未捕获，则返回 cudaErrorIllegalState 错误。

注意

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

另请参阅

cudaStreamBeginCapture, cudaStreamGetCaptureInfo,

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

使计算流等待事件。

参数

stream: - 要等待的流
event: - 要等待的事件
flags: - 操作参数（见上文）

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle

描述

使所有未来提交到以下项的工作stream等待以下项中捕获的所有工作event。有关事件捕获内容的详细信息，请参阅 cudaEventRecord()。同步将在设备上高效执行（如果适用）。event可能来自与以下项不同的设备stream.

标志包括

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

注意

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

另请参阅

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

__host__ cudaError_t cudaThreadExchangeStreamCaptureMode ( cudaStreamCaptureMode ** mode )

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

参数

mode: - 指向要与当前模式交换的模式值的指针

返回值

cudaSuccess, cudaErrorInvalidValue

描述

将调用线程的流捕获交互模式设置为以下项中包含的值：*mode，并覆盖*mode为线程的先前模式。为了方便跨函数或模块边界的确定性行为，鼓励调用者以 push-pop 方式使用此 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。

注意

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

另请参阅

cudaStreamBeginCapture