跳到主要内容

通信器的创建和管理函数

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

ncclGetLastError​

返回NCCL中最后发生的错误的可读字符串。注意：调用此函数不会清除错误。当前未使用comm参数，可以设置为NULL。

ncclGetVersion​

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

ncclGetUniqueId​

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

ncclCommInitRank​

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

ncclCommInitAll​

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

ncclCommInitRankConfig​

该函数与ncclCommInitRank的工作方式相同，但接受一个配置参数，用于配置通信器的额外属性。如果将配置设置为NULL，则通信器将具有默认行为，就像调用ncclCommInitRank一样。

有关配置选项的详细信息，请参阅init-rank-config部分。

ncclCommSplit​

ncclCommSplit函数从现有通信器创建一组新的通信器。传递相同color值的rank将成为同一组的一部分，颜色必须是非负值。如果将其传递为NCCL_SPLIT_NOCOLOR，则意味着该rank不属于任何组，因此将返回新的通信器为NULL。key的值将确定rank顺序，较小的key在新的通信器中具有较小的rank。如果rank之间的key相等，则将使用原始通信器中的rank来排序rank。如果新通信器需要具有特殊配置，则可以将其作为config传递，否则将config设置为NULL将使新通信器继承原始通信器的配置。在分裂时，comm上不应有任何未完成的NCCL操作。否则，可能会引起死锁。

ncclCommFinalize​

完成一个通信器对象comm的初始化。当通信器标记为非阻塞时，ncclCommFinalize是一个非阻塞函数。成功返回将把通信器状态设置为ncclInProgress，表示通信器正在进行最终处理，其中包括刷新和释放所有未完成的操作和网络相关资源。一旦所有的NCCL操作完成，通信器将转换到ncclSuccess状态。用户可以使用ncclCommGetAsyncError查询该状态。

ncclCommDestroy​

销毁通信器对象comm。ncclCommDestroy仅释放之前在通信器对象comm上分配的本地资源，如果之前对通信器进行了ncclCommFinalize，否则ncclCommDestroy将在内部调用ncclCommFinalize。如果用户调用了ncclCommFinalize，必须保证在调用ncclCommDestroy之前通信器的状态变为ncclSuccess。在所有情况下，在ncclCommDestroy返回后不应再访问通信器。建议用户先调用ncclCommFinalize，然后再调用ncclCommDestroy。

ncclCommAbort​

释放给通信器对象comm分配的资源。在销毁通信器之前，会中止所有未完成的操作。

ncclCommGetAsyncError​

查询异步NCCL操作的进度和潜在错误。不需要流参数的操作（例如ncclCommFinalize）可以在函数返回ncclSuccess时视为已完成；带有流参数的操作（例如ncclAllReduce）在操作在流上发布后会立即返回ncclSuccess，但也可能通过ncclCommGetAsyncError()报告错误，直到操作完成。如果任何NCCL函数的返回代码是ncclInProgress，意味着操作正在后台排队，用户必须查询通信器的状态，直到所有状态变为ncclSuccess，然后再调用下一个NCCL函数。在状态变为ncclSuccess之前，用户不允许向NCCL使用的流中发出CUDA内核。如果通信器发生错误，用户应该使用ncclCommAbort来销毁通信器。如果通信器发生错误，不能假设对该通信器上排队的操作的完成或正确性。

ncclCommCount​

在NCCL通信器comm中返回count个进程的数量。

ncclCommCuDevice​

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

ncclCommUserRank​

返回NCCL通信器comm的进程的rank在rank中。

ncclCommRegister​

向通信器comm注册大小为size的缓冲区，以进行零拷贝通信，并返回handle以供将来注销使用。参见buff和size的要求[user_buffer_reg]。

ncclCommDeregister​

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

ncclMemAlloc​

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

ncclMemFree​

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