通信器创建和管理函数

以下函数是由 NCCL 公开的公共 API，用于创建和管理集体通信操作。

ncclGetLastError

const char* ncclGetLastError(ncclComm_t comm)

返回一个人类可读的字符串，对应于 NCCL 中发生的最后一个错误。注意：调用此函数不会清除错误。请注意，ncclGetLastError 返回的字符串可能与当前调用无关，并且可能是先前启动的异步操作的结果（如果有）。

ncclGetErrorString

const char* ncclGetErrorString(ncclResult_t result)

返回一个人类可读的字符串，对应于传递的错误代码。

ncclGetVersion

ncclResult_t ncclGetVersion(int* version)

ncclGetVersion 函数返回当前链接的 NCCL 库的版本号。NCCL 版本号在 version 中返回，并编码为包含 NCCL_MAJOR、NCCL_MINOR 和 NCCL_PATCH 级别的整数。返回的版本号将与 nccl.h 中定义的 NCCL_VERSION_CODE 相同。NCCL 版本号可以使用提供的宏进行比较；NCCL_VERSION(MAJOR,MINOR,PATCH)

ncclGetUniqueId

ncclResult_t ncclGetUniqueId(ncclUniqueId* uniqueId)

生成用于 ncclCommInitRank 的 ID。创建通信器时应调用一次 ncclGetUniqueId，并且在调用 ncclCommInitRank 之前，应将 ID 分发给通信器中的所有 rank。uniqueId 应指向用户分配的 ncclUniqueId 对象。

ncclCommInitRank

ncclResult_t ncclCommInitRank(ncclComm_t* comm, int nranks, ncclUniqueId commId, int rank)

创建一个新的通信器（多线程/进程版本）。rank 必须介于 0 和 nranks-1 之间，并且在通信器集群中是唯一的。每个 rank 都与一个 CUDA 设备关联，该设备必须在调用 ncclCommInitRank 之前设置。ncclCommInitRank 隐式地与其他 rank 同步，因此必须由不同的线程/进程调用，或者在 ncclGroupStart/ncclGroupEnd 中使用。

ncclCommInitAll

ncclResult_t ncclCommInitAll(ncclComm_t* comms, int ndev, const int* devlist)

以阻塞方式创建一个通信器集群（单进程版本）。这是一个方便的函数，用于创建单进程通信器集群。在 comms 中返回 ndev 个新初始化的通信器数组。comms 应预先分配至少 ndev*sizeof(ncclComm_t) 的大小。devlist 定义了与每个 rank 关联的 CUDA 设备。如果 devlist 为 NULL，则按顺序使用前 ndev 个 CUDA 设备。

ncclCommInitRankConfig

ncclResult_t ncclCommInitRankConfig(ncclComm_t* comm, int nranks, ncclUniqueId commId, int rank, ncclConfig_t* config)

此函数的工作方式与 ncclCommInitRank 相同，但接受一个配置参数，其中包含通信器的额外属性。如果 config 作为 NULL 传递，则通信器将具有默认行为，就像调用了 ncclCommInitRank 一样。

有关配置选项的详细信息，请参阅使用选项创建通信器部分。

ncclCommInitRankScalable

ncclResult_t ncclCommInitRankScalable(ncclComm_t* newcomm, int nranks, int myrank, int nId, ncclUniqueId* commIds, ncclConfig_t* config)

此函数的工作方式与 ncclCommInitRankConfig 相同，但接受 ncclUniqueId 列表而不是单个 ID。如果只传递一个 ncclUniqueId，则将初始化通信器，就像调用了 ncclCommInitRankConfig 一样。提供的 ncclUniqueId 都将用于初始化参数中给定的单个通信器。

有关如何创建和分发 ncclUniqueId 列表的详细信息，请参阅使用选项创建通信器部分。

ncclCommSplit

ncclResult_t ncclCommSplit(ncclComm_t comm, int color, int key, ncclComm_t* newcomm, ncclConfig_t* config)

ncclCommSplit 是一个集体函数，它从现有通信器创建一组新的通信器。传递相同 color 值的 rank 将成为同一组的一部分；color 必须是非负值。如果作为 NCCL_SPLIT_NOCOLOR 传递，则表示该 rank 将不属于任何组，因此返回 NULL 作为 newcomm。key 的值将决定 rank 的顺序，较小的 key 表示新通信器中较小的 rank。如果 rank 之间的 key 相等，则将使用原始通信器中的 rank 对 rank 进行排序。如果新通信器需要具有特殊配置，则可以将其作为 config 传递，否则将 config 设置为 NULL 将使新通信器继承原始通信器的配置。拆分时，comm 上不应有任何未完成的 NCCL 操作。否则，可能会导致死锁。

ncclCommFinalize

ncclResult_t ncclCommFinalize(ncclComm_t comm)

完成通信器对象 comm。当通信器标记为非阻塞时，ncclCommFinalize 是一个非阻塞函数。从它成功返回会将通信器状态设置为 ncclInProgress，并指示通信器正在完成，其中所有未完成的操作和与网络相关的资源正在被刷新和释放。一旦所有 NCCL 操作完成，通信器将转换为 ncclSuccess 状态。用户可以使用 ncclCommGetAsyncError 查询该状态。

ncclCommDestroy

ncclResult_t ncclCommDestroy(ncclComm_t comm)

销毁通信器对象 comm。如果先前在通信器上调用了 ncclCommFinalize，则 ncclCommDestroy 仅释放分配给通信器对象 comm 的本地资源；否则，ncclCommDestroy 将在内部调用 ncclCommFinalize。如果用户调用 ncclCommFinalize，则用户应保证通信器的状态在调用 ncclCommDestroy 之前变为 ncclSuccess。在任何情况下，在 ncclCommDestroy 返回后，都不应再访问该通信器。建议用户先调用 ncclCommFinalize，然后再调用 ncclCommDestroy。此函数是节点内集体调用，同一节点上的所有 rank 都应调用此函数以避免挂起。

ncclCommAbort

ncclResult_t ncclCommAbort(ncclComm_t comm)

ncclCommAbort 释放分配给通信器对象 comm 的资源，并在销毁通信器之前中止任何未完成的操作。所有活动 rank 都需要调用此函数，以便成功中止 NCCL 通信器。有关更多用例，请查看容错。

ncclCommGetAsyncError

ncclResult_t ncclCommGetAsyncError(ncclComm_t comm, ncclResult_t* asyncError)

查询异步 NCCL 操作的进度和潜在错误。不需要流参数的操作（例如 ncclCommFinalize）可以在函数返回 ncclSuccess 后立即被视为完成；带有流参数的操作（例如 ncclAllReduce）将在操作发布到流上后立即返回 ncclSuccess，但也可能通过 ncclCommGetAsyncError() 报告错误，直到它们完成。如果任何 NCCL 函数的返回代码为 ncclInProgress，则表示该操作正在后台排队，用户必须查询通信器的状态，直到所有状态变为 ncclSuccess 后才能调用另一个 NCCL 函数。在状态变为 ncclSuccess 之前，不允许用户向 NCCL 使用的流发出 CUDA 内核。如果通信器上出现错误，用户应使用 ncclCommAbort() 销毁通信器。如果通信器上发生错误，则无法假定在该通信器上排队的操作的完成或正确性。

ncclCommCount

ncclResult_t ncclCommCount(const ncclComm_t comm, int* count)

在 count 中返回 NCCL 通信器 comm 中的 rank 数量。

ncclCommCuDevice

ncclResult_t ncclCommCuDevice(const ncclComm_t comm, int* device)

在 device 中返回与 NCCL 通信器 comm 关联的 CUDA 设备。

ncclCommUserRank

ncclResult_t ncclCommUserRank(const ncclComm_t comm, int* rank)

在 rank 中返回调用者在 NCCL 通信器 comm 中的 rank。

ncclCommRegister

ncclResult_t ncclCommRegister(const ncclComm_t comm, void* buff, size_t size, void** handle)

在通信器 comm 下注册大小为 size 的缓冲区 buff，用于零拷贝通信；handle 返回用于将来的注销。有关 buff 和 size 要求以及更多说明，请参阅用户缓冲区注册。

ncclCommDeregister

ncclResult_t ncclCommDeregister(const ncclComm_t comm, void* handle)

注销通信器 comm 下由 handle 表示的缓冲区。

ncclMemAlloc

ncclResult_t ncclMemAlloc(void **ptr, size_t size)

分配大小为 size 的 GPU 缓冲区。分配的缓冲区头地址将由 ptr 返回，并且由于所有类型的 NCCL 优化的缓冲区粒度要求，实际分配的大小可能大于请求的大小。

ncclMemFree

ncclResult_t ncclMemFree(void *ptr)

释放由 ncclMemAlloc() 分配的内存。