Skip to main content

通信器创建和管理函数

以下是由 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 设备。

mcclMemAlloc​

mcclResult_t mcclMemAlloc(void** ptr, size_t size)

为 MCCL 优化路径分配 MUSA 内存，例如用户缓冲区注册、对称窗口和相关通信场景。由于底层分配粒度要求，实际保留的底层分配范围可能大于请求的 size，但返回给用户的仍是可按请求大小使用的缓冲区指针。

ptr 必须指向用户提供的输出指针；size 必须大于 0。

mcclMemFree​

mcclResult_t mcclMemFree(void* ptr)

释放由 mcclMemAlloc 返回的缓冲区。

mcclCommGetUniqueId​

mcclResult_t mcclCommGetUniqueId(mcclComm_t comm, mcclUniqueId* uniqueId)

从一个已存在的通信器派生出 grow 专用的唯一 ID，供后续 mcclCommGrow 使用。

约束如下：

  • 在前一个 grow unique ID 尚未被消费完成前，不能再次生成新的 grow unique ID
  • 每个 grow unique ID 只能使用一次
  • grow 结束前不应再次发起 grow

此接口不同于用于初始建群的 mcclGetUniqueId。

mcclCommGrow​

mcclResult_t mcclCommGrow(mcclComm_t comm, int nRanks, const mcclUniqueId* uniqueId, int rank, mcclComm_t* newcomm, mcclConfig_t* config)

将一个已有通信器扩展到更大的 nRanks。

调用约定：

  • 已有 rank：传入已有 comm，并设置 rank = -1
  • 已有 rank 中负责提供 grow ID 的 rank：传入 comm、rank = -1 和由 mcclCommGetUniqueId 生成的 uniqueId
  • 其他已有 rank：通常传入 comm、rank = -1，并令 uniqueId = NULL
  • 新 rank：传入 comm == NULL、非空 uniqueId 和新通信器中的 rank 编号

config 用于指定新通信器配置；为 NULL 时使用默认配置。

补充说明：

  • 从单 rank 通信器扩容时，已有 rank 必须传入 grow uniqueId
  • nRanks 必须严格大于原通信器的 rank 数量

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() 销毁通信器，不能假定在该通信器上已排队操作的完成性或正确性。

对于非阻塞通信器，此接口也用于查询后台状态推进结果。在非阻塞初始化、mcclCommFinalize、mcclCommRevoke 等阶段，*asyncError 可能返回 mcclInProgress；调用方应持续轮询，直到状态变为 mcclSuccess 或某个错误码，再决定后续的 destroy/abort 流程。

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 将包含可用于后续注销操作的句柄。

补充说明：

  • 此接口注册的是用户已经拥有的缓冲区，本身不负责分配用户缓冲区
  • 在某些运行条件下，MCCL 可能跳过本次注册并返回 mcclSuccess，同时令 *handle = NULL

mcclCommDeregister​

mcclResult_t mcclCommDeregister(const mcclComm_t comm, void* handle)

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

mcclCommWindowRegister​

mcclResult_t mcclCommWindowRegister(mcclComm_t comm, void* buff, size_t size, mcclWindow_t* win, int flags)

在通信器上注册一个窗口对象。mcclWinGetUserPtr、mcclGetLsaDevicePointer 以及 RMA signal 接口都依赖窗口注册能力。

常用标志：

  • MCCL_WIN_DEFAULT
  • MCCL_WIN_COLL_SYMMETRIC

补充说明：

  • 返回 mcclSuccess 并不等价于“该通信器已经具备对称窗口能力”
  • 在不支持相关能力的通信器上，此接口可能退化为 unsupported fallback：返回 mcclSuccess，同时令 *win == NULL
  • 在使用 mcclWinGetUserPtr、mcclGetLsaDevicePointer 或 RMA signal 相关接口前，应先通过 mcclCommQueryProperties 检查能力，并校验返回的 win 是否为非空

mcclCommWindowDeregister​

mcclResult_t mcclCommWindowDeregister(mcclComm_t comm, mcclWindow_t win)

注销之前注册的窗口对象，释放与该窗口相关的 MCCL 资源。

mcclWinGetUserPtr​

mcclResult_t mcclWinGetUserPtr(mcclComm_t comm, mcclWindow_t win, void** outUserPtr)

返回窗口对应的原始用户指针。

特殊语义：

  • 对于支持对称窗口辅助能力的通信器，win 必须有效
  • 对于不支持该能力的通信器，win == NULL 的能力探测路径可能返回成功并把 *outUserPtr 置为 NULL

该接口主要用于能力探测和调试，不应把特殊 fallback 路径等同于通用参数校验行为。

mcclCommQueryProperties​

mcclResult_t mcclCommQueryProperties(mcclComm_t comm, mcclCommProperties* props)

查询通信器能力属性。

props 应使用 MCCL_COMM_PROPERTIES_INITIALIZER 初始化。常见返回字段包括：

  • rank
  • nRanks
  • musaDev
  • deviceApiSupport
  • multimemSupport
  • ginType
  • nLsaTeams
  • hostRmaSupport
  • railedGinType

mcclGetLsaDevicePointer​

mcclResult_t mcclGetLsaDevicePointer(mcclWindow_t win, size_t offset, int lsaRank, void** outPtr)

返回对称窗口在指定 lsaRank 视角下的设备指针。该接口是主机侧辅助接口，通常用于 LSA 调试、验证或桥接逻辑。

mcclCommSuspend​

mcclResult_t mcclCommSuspend(mcclComm_t comm, int flags)

挂起通信器中指定类别的资源。当前公开支持的标志为：

  • MCCL_SUSPEND_MEM

这是一个通信器级别的集体调用。调用前必须确保没有用户 kernel 正在访问 MCCL 跟踪的动态内存，并且同一通信器上的相关 host API 已完成外部串行化。

mcclCommResume​

mcclResult_t mcclCommResume(mcclComm_t comm)

恢复之前由 mcclCommSuspend 成功挂起的通信器资源。与 mcclCommSuspend 一样，这是一个通信器级别的集体调用，并要求同一通信器上的相关 host API 外部串行化。

mcclCommMemStats​

mcclResult_t mcclCommMemStats(mcclComm_t comm, mcclCommMemStat_t stat, uint64_t* value)

查询通信器内存管理器维护的逻辑统计值。

典型 stat 包括：

  • mcclStatGpuMemSuspend
  • mcclStatGpuMemSuspended
  • mcclStatGpuMemPersist
  • mcclStatGpuMemTotal

返回的 size 类统计值以字节为单位。该接口仅反映被通信器内存管理器成功跟踪的内存。

补充说明：

  • 这些统计值不是全局显存统计，而是通信器内存管理器的逻辑统计值
  • 仅在同一通信器上没有其他内存管理 host API 并发执行时，才支持并发调用 mcclCommMemStats
  • 当通信器内存管理功能被禁用，或内存管理器处于瞬态/错误状态时，该接口返回 mcclInvalidUsage

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

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

免责声明

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