跳到主要内容

通信器创建和管理函数

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

mcclGetLastError​

const char* mcclGetLastError(mcclComm_t comm)

返回对应于 MCCL 中最后一次发生的错误的可读字符串。调用此函数不会清除错误。注意：mcclGetLastError 返回的字符串可能与当前调用无关，它也可能来自先前启动的异步操作的结果。

mcclGetErrorString​

const char* mcclGetErrorString(mcclResult_t result)

返回对应于传递的错误代码的可读字符串。

mcclGetVersion​

mcclResult_t mcclGetVersion(int* version)

mcclGetVersion 函数返回当前链接的 MCCL 库的版本号。存放于 version 指向的整数中。该整数按约定编码了 MCCL_MAJOR、MCCL_MINOR 和 MCCL_PATCH 三个字段。返回的版本号将与 mccl.h 中定义的 MCCL_VERSION_CODE 相同。MCCL 版本号可以使用提供的宏进行比较；MCCL_VERSION(MAJOR,MINOR,PATCH)

mcclGetUniqueId​

mcclResult_t mcclGetUniqueId(mcclUniqueId* uniqueId)

生成一个用于 mcclCommInitRank 的唯一 ID。创建通信器时，应先调用一次 mcclGetUniqueId 并将产生的 ID 分发给通信器中的所有 rank，然后再调用 mcclCommInitRank。uniqueId 应指向用户分配的 mcclUniqueId 对象。

mcclCommInitRank​

mcclResult_t mcclCommInitRank(mcclComm_t* comm, int nranks, mcclUniqueId commId, int rank)

创建一个新的通信器（多线程/进程版本）。rank 必须在 0 和 nranks - 1 之间，并且在通信器域内是唯一的。每个 rank 都与一个 MUSA 设备关联，必须在调用 mcclCommInitRank 之前设置。mcclCommInitRank 隐式地与其他 rank 同步，因此必须由不同的线程/进程调用，或在 mcclGroupStart 与 mcclGroupEnd 内使用。

mcclCommInitAll​

mcclResult_t mcclCommInitAll(mcclComm_t* comms, int ndev, const int* devlist)

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

mcclCommDestroy​

mcclResult_t mcclCommDestroy(mcclComm_t comm)

释放分配给通信器对象 comm 的资源。在销毁通信器之前等待任何未完成的操作。

mcclCommAbort​

mcclResult_t mcclCommAbort(mcclComm_t comm)

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

mcclCommGetAsyncError​

mcclResult_t mcclCommGetAsyncError(mcclComm_t comm, mcclResult_t* asyncError)

查询通信器异步操作的进度和潜在错误。如果通信器上发生错误，用户应该使用 mcclCommAbort() 销毁通信器，不能假定在该通信器上已排队操作的完成性或正确性。

mcclCommCount​

mcclResult_t mcclCommCount(const mcclComm_t comm, int* count)

返回 MCCL 通信器 comm 中的 rank 数量。

mcclCommMuDevice​

mcclResult_t mcclCommMuDevice(const mcclComm_t comm, int* device)

返回与 MCCL 通信器 comm 关联的 MUSA 设备。

mcclCommUserRank​

mcclResult_t mcclCommUserRank(const mcclComm_t comm, int* rank)

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

mcclCommInitRankConfig​

mcclResult_t mcclCommInitRankConfig(mcclComm_t* comm, int nranks, mcclUniqueId commId, int rank, mcclConfig_t* config)

使用用户指定的配置创建一个新通信器（多线程/进程版本）。rank 必须在 0 和 nranks - 1 之间，并且在通信器域内是唯一的。每个 rank 都与一个 MUSA 设备关联，必须在调用 mcclCommInitRankConfig 之前设置。mcclCommInitRankConfig 隐式地与其他 rank 同步，因此必须由不同的线程/进程调用，或在 mcclGroupStart 与 mcclGroupEnd 内使用。

config 参数允许用户自定义通信器的行为，如阻塞模式、CTA 策略等。如果 config 为 NULL，则使用默认配置。

mcclCommInitRankScalable​

mcclResult_t mcclCommInitRankScalable(mcclComm_t* newcomm, int nranks, int myrank, int nId, mcclUniqueId* commIds, mcclConfig_t* config)

创建一个新通信器（多线程/进程版本），类似于 mcclCommInitRankConfig。允许使用多个 mcclUniqueId（最多每个 rank 一个），由 nId 指示，以加速初始化操作。mcclUniqueId 的数量及其顺序对每个 rank 必须相同。

此函数适用于大规模集群场景，通过使用多个唯一 ID 来减少初始化时的网络瓶颈。

mcclCommFinalize​

mcclResult_t mcclCommFinalize(mcclComm_t comm)

完成通信器。mcclCommFinalize 会刷新所有已发出的通信操作，并将通信器状态标记为 mcclInProgress。当通信器全局静默且相关资源被释放后，状态将变为 mcclSuccess；此时调用 mcclCommDestroy 可以在本地释放其余资源（如通信器本身）而不会阻塞。

此函数用于优雅地关闭通信器，确保所有进行中的操作完成后再释放资源。

mcclCommRevoke​

mcclResult_t mcclCommRevoke(mcclComm_t comm, int revokeFlags)

撤销通信器。mcclCommRevoke 停止所有进行中的操作，并将通信器状态标记为 mcclInProgress。当通信器静默后，状态将变为 mcclSuccess，此时可以安全地执行管理操作（destroy、split、shrink）。在撤销后调用 mcclCommFinalize 是无效的。此外，撤销期间通过 splitShare/shrinkShare 进行的资源共享被禁用。

revokeFlags 必须为 MCCL_REVOKE_DEFAULT (0)。

相关链接：容错。

mcclCommSplit​

mcclResult_t mcclCommSplit(mcclComm_t comm, int color, int key, mcclComm_t* newcomm, mcclConfig_t* config)

从现有通信器创建一个或多个新通信器。具有相同 color 的 rank 将被分到同一个通信器中。在新通信器内，key 用于对 rank 进行排序。MCCL_SPLIT_NOCOLOR 作为 color 表示该 rank 不会加入任何组，因此将返回 NULL 通信器。

如果 config 为 NULL，新通信器将继承原始通信器的配置。

此函数可用于将大型通信器分割为更小的子组，以便进行更细粒度的并行计算。

mcclCommShrink​

mcclResult_t mcclCommShrink(mcclComm_t comm, int* excludeRanksList, int excludeRanksCount, mcclComm_t* newcomm, mcclConfig_t* config, int shrinkFlags)

收缩现有通信器。excludeRanksList 中的 rank 将从现有通信器中移除。在新通信器中，rank 将重新排序以填补被移除的 rank 的空缺。

如果 config 为 NULL，新通信器将继承原始通信器的配置。shrinkFlags 参数支持以下标志：

  • MCCL_SHRINK_DEFAULT (0): 收缩父通信器
  • MCCL_SHRINK_ABORT (1): 首先终止父通信器上正在进行的操作，然后收缩父通信器

此函数用于从通信器中移除故障或退出的 rank，实现容错能力。

mcclCommRegister​

mcclResult_t mcclCommRegister(const mcclComm_t comm, void* buff, size_t size, void** handle)

注册 MUSA 缓冲区以进行零拷贝操作。注册后的缓冲区可以用于优化的数据传输路径，提高通信性能。实际分配的内存可能由于粒度要求而大于请求的大小。

注册后，handle 将包含可用于后续注销操作的句柄。

mcclCommDeregister​

mcclResult_t mcclCommDeregister(const mcclComm_t comm, void* handle)

注销 MUSA 缓冲区。释放与之前注册的缓冲区相关联的资源。必须在通信器销毁之前注销所有已注册的缓冲区。

版权所有 2024 摩尔线程，本文档受国际版权法保护。

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。