HcommChannelCreate

Applicability

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

Function

Creates communication channels in batches based on the given channel description and the created network endpoints, providing the infrastructure for data transmission in point-to-point communication or collective communication.

Prototype

HcommResult HcommChannelCreate(EndpointHandle endpointHandle, CommEngine engine, HcommChannelDesc *channelDescs, uint32_t channelNum, ChannelHandle *channels);

Parameters

Parameter	Input/Output	Description
endpointHandle	Input	Handle to a network device endpoint, which identifies a created local network device endpoint. For details, see EndpointHandle. The handle must be successfully created by using HcommEndpointCreate and has not been destroyed.
engine	Input	Communication engine type, which specifies the execution location of the channel. For details, see CommEngine. Note that the engine type must be valid.
channelDescs	Input	Channel descriptor array. Each element describes the attributes of a channel to be created. For details, see HcommChannelDesc. The number of elements in the array must be equal to the value of channelNum. Each element must be correctly filled with necessary fields.
channelNum	Input	Number of channels to be created. Value range: [1, 1048576]. The value must be greater than 0.
channels	Output	Channel handle array, which is used to return the list of handles of successfully created channels. For details, see ChannelHandle. The array allocated by the caller must contain at least channelNum elements.

Returns

HcommResult: 0 on success; else, failure.

Restrictions

The length of the channelDescs array must be the same as that of the channelNum parameter.
The remote endpoint information in remoteEndpoint of HcommChannelDesc must be correctly filled.
When exchangeAllMems in HcommChannelDesc is set to false, memHandles and memHandleNum must also be configured.
When CommEngine is set to CCU, only one memHandle can be exchanged.
When CommEngine is set to CCU, NotifyNum cannot be configured externally. By default, eight CCU Notify resources are configured.

Example

EndpointHandle endpointHandle = nullptr;
 //... Create endpoints (code omitted).

 // Create multiple channels.
 const uint32_t CHANNEL_NUM = 4;
 HcommChannelDesc channelDescs[CHANNEL_NUM] = {0};
 ChannelHandle channels[CHANNEL_NUM] = {0};

 // Prepare the channel descriptor and create channels.
 for (uint32_t i = 0; i < CHANNEL_NUM; i++) {
     //... Fill in channelDescs[i].
 }

 HcommResult ret = HcommChannelCreate(endpointHandle, COMM_ENGINE_CPU,
                                      channelDescs, CHANNEL_NUM, channels);
 if (ret != 0) {
     printf("Failed to create channels, ret = %d\n", ret);
     HcommEndpointDestroy(endpointHandle);
     return ret;
 }

 printf("%u channels created successfully\n", CHANNEL_NUM);

Parent topic: Basic Resource Management