HcclChannelAcquire

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product/Atlas A3 inference product	√
Atlas A2 training product/Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	x
Atlas inference product	x
Atlas training product	x

For Atlas A2 training product/Atlas A2 inference product, only the Atlas 800T A2 training server, Atlas 900 A2 PoD cluster basic unit, and Atlas 200T A2 Box16 heterogeneous subrack are supported.

Function

Obtains multiple communication channels based on the communicator. If the communicator does not have the corresponding communication channel, the communication channel is directly created.

Whether the channel is reused is determined based on the unique channel ID consisting of commId, engine, remoterank, and channelProtocol.

Prototype

HcclResult HcclChannelAcquire(HcclComm comm, CommEngine engine, const HcclChannelDesc *channelDescs, uint32_t channelNum, ChannelHandle *channels)

Parameters

Parameter

Input/Output

Description

comm

Input

Communicator handle.

The HcclComm type is defined as follows:

typedef void *HcclComm;

engine

Input

Communication engine type.

For the definition of the CommEngine type, see CommEngine.

channelDescs

Input

Communication channel description list. The list length is channelNum.

For the definition of the HcclChannelDesc type, see HcclChannelDesc. You can obtain the value by calling HcclRankGraphGetLinks.

channelNum

Input

Number of communication channels. The value range is (0, 1024 × 1024].

channels

Output

List of communication channel handles. The list length is channelNum.

Returns

HcclResult: HCCL_SUCCESS on success, or else failure.

Restrictions

When CommEngine is set to CCU, NotifyNum cannot be configured externally. By default, eight CCU Notify resources are configured.

When CommEngine is set to CCU, additional custom memory cannot be exchanged. Only the HcclBuffer of the communicator can be exchanged.

Example

The following uses batch communication channels as an example:

// 1. Call HcclRankGraphGetLinks to obtain link information.
CommLink *linkList = nullptr;
uint32_t listSize;
CHK_RET(HcclRankGraphGetLinks(comm, netLayer, myRank, rank, &linkList, &listSize));

// 2. Traverse each CommLink and fill in HcclChannelDesc.
uint32_t channelNum = listSize;
std::vector<HcclChannelDesc> channelDescVec(channelNum);
for (uint32_t idx = 0; idx < listSize; idx++) {
  HcclChannelDesc channelDesc;
  HcclChannelDescInit(&channelDesc, 1);
  channelDesc.remoteRank = rank;

  CommLink link = linkList[idx];

  // Core mapping: Extract endpoints from CommLink.
  channelDesc.localEndpoint.protocol = link.srcEndpointDesc.protocol;
  channelDesc.localEndpoint.commAddr = link.srcEndpointDesc.commAddr;
  channelDesc.localEndpoint.loc    = link.srcEndpointDesc.loc;
  channelDesc.remoteEndpoint.protocol = link.dstEndpointDesc.protocol;
  channelDesc.remoteEndpoint.commAddr = link.dstEndpointDesc.commAddr;
  channelDesc.remoteEndpoint.loc   = link.dstEndpointDesc.loc;
  channelDesc.channelProtocol     = link.linkAttr.linkProtocol;
  channelDesc.notifyNum = NORMAL_NOTIFY_NUM;

  channelDescVec[idx] = channelDesc;
}

// 3. Create channels in batches.
HcclComm comm;
CommEngine engine = CommEngine::COMM_ENGINE_CPU_TS;
std::vector<ChannelHandle> channels(channelNum);
HcclChannelAcquire(comm, engine, channelDescVec.data(), channelNum, channels.data());

Parent topic: Communicator Resource Management