Initialize
Applicability
|
Product |
Supported (√/x) |
|---|---|
|
Atlas 350 Accelerator Card |
x |
|
|
√ |
|
|
√ |
|
|
x |
|
|
x |
|
|
x |
Note: For
Function Description
Initializes an HIXL instance. This API must be called before other APIs are called.
Prototype
1
|
Status Initialize(const AscendString &local_engine, const std::map<AscendString, AscendString> &options) |
Parameters
|
Parameter |
Input/Output |
Description |
|---|---|---|
|
local_engine |
Input |
HIXL identifier, which must be unique among all participants in the link establishment.
You are advised not to set this parameter to a loopback IP address, as it may lead to conflicts in scenarios involving multiple HIXL instances. If host_port is set and its value is greater than 0, the current HIXL instance functions as the server and needs to listen on the specified port. If host_port is not set or its value is less than or equal to 0, the current HIXL instance functions as the client and will not start listening. |
|
options |
Input |
Initialization parameter values. For details, see the following table. |
The configuration examples and usage restrictions of `OPTION_GLOBAL_RESOURCE_CONFIG` are as follows:
For the Fabric Mem mode (supported only by
{
"fabric_memory.max_capacity": "128", //Size of the virtual memory pool. Value range: an integer in the range (0, 1024]. Default value: 64. Unit: TB.
"fabric_memory.task_stream_num": "1", //Number of streams used by a single task in Fabric Mem mode. Value range: an integer in the range [1, 8]. Default value: 4.
}
The following is an example of setting parameters for the link pool mechanism:
{
"channel_pool.max_channel": "10", //Maximum number of links. Value range: an integer in the range (0, 512]. Default value: 512.
"channel_pool.high_waterline": "0.3", //High watermark for triggering link destruction. Value range: a decimal number in the range (0, 1). This parameter must be configured together with channel_pool.low_waterline.
"channel_pool.low_waterline": "0.1" //Low watermark for triggering link destruction. Value range: a decimal number in the range (0, 1). The value must be less than the high watermark.
}
The channel pool determines destruction based on the current channel count. If the count reaches the high watermark, it destroys (Current count – Low watermark) channels, skipping any that are actively transmitting before establishing a new connection. The relevant parameters are calculated as follows:
- Channels at high watermark = max(1,static_cast<int32_t> (channel_pool.max_channel * channel_pool.high_waterline))
- Channels at low watermark = max(1,static_cast<int32_t> (channel_pool.max_channel * channel_pool.low_waterline))
In the example above, the high and low watermarks evaluate to 3 and 1, respectively. Before each new connection, the system checks if the HIXL channel count has reached 3. If so, it destroys (Current count – 1) idle channels before proceeding with the new connection.
Before enabling the link pool mechanism, pay attention to the following:
- OPTION_GLOBAL_RESOURCE_CONFIG must be configured for all HIXL Engines in the cluster.
- When the TransferSync or TransferAsync API is called, if no related link exists, a new link will be established.
- This increases the extra overhead for transmission and link establishment, which may lead to performance deterioration.
Example
Click GitCode, select the matching version, and obtain the sample from the examples/cpp directory.
Returns
- SUCCESS: Success.
- PARAM_INVALID: Incorrect parameter.
- Other values: Failure.
Exception Handling
None
Restrictions
- This API must be used in conjunction with Finalize. After successful initialization, Finalize must be called before any exit to ensure resource release. Otherwise, issues may arise due to unexpected resource release order.
- Before initialization, aclrtSetDevice in Application Development (C&C++) must be called.