cann-robot[feat]: support configurable max active channels

a79269ce创建于 2 天前历史提交

HIXL CS 接口说明

产品支持情况

Ascend 950PR/Ascend 950DT：支持

Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

Atlas A2 推理系列产品/Atlas A2 训练系列产品：支持

HixlStatus与返回码

接口返回码类型与常量。

typedef uint32_t HixlStatus;
static const uint32_t HIXL_SUCCESS = 0U;
static const uint32_t HIXL_PARAM_INVALID = 103900U;
static const uint32_t HIXL_TIMEOUT = 103901U;
static const uint32_t HIXL_FAILED = 503900U;

具体错误码含义如下。

枚举值	含义	是否可恢复	解决办法
HIXL_SUCCESS	成功	无	不涉及。
HIXL_PARAM_INVALID	参数错误	是	基于日志排查错误原因。
HIXL_TIMEOUT	处理超时	否	保留现场，获取Host/Device日志，并备份。
HIXL_FAILED	通用失败	否	保留现场，获取Host/Device日志，并备份。

句柄类型

句柄类型定义。

typedef void *HixlServerHandle;
typedef void *HixlClientHandle;
typedef void *CompleteHandle;
typedef void *MemHandle;

结构体说明

以下是CS API中使用到的结构体定义。

HixlServerConfig

Server配置。

struct HixlServerConfig {
  const char *global_resource_config = nullptr;
  uint8_t reserved[120] = {};
};

字段说明：

字段	类型	描述
global_resource_config	const char*	全局资源配置，JSON字符串，当前用于配置Server侧通信资源参数。可传入NULL或空字符串表示不配置。
reserved	uint8_t[120]	HixlServerConfig配置保留字段，用于未来扩展，结构体总大小保持为128字节。

HixlClientConfig

Client配置。

struct HixlClientConfig {
  const char *global_resource_config = nullptr;
  uint8_t reserved[120] = {};
};

字段说明：

字段	类型	描述
global_resource_config	const char*	全局资源配置，JSON字符串，当前用于配置Client侧通信资源参数。可传入NULL或空字符串表示不配置。
reserved	uint8_t[120]	HixlClientConfig配置保留字段，用于未来扩展，结构体总大小保持为128字节。

global_resource_config配置说明

Server侧global_resource_config当前支持的配置项如下。

配置项	类型	是否必选	描述
comm_resource_config.listen_port	整数	可选	配置CS建链时Server侧通信资源监听端口，取值范围为[1, 65535]。Server配置该字段后，会在Client建链匹配Endpoint阶段通过响应返回该端口；未配置时，Server保持原有自动查询监听端口逻辑；取值不在范围内时，Server创建失败并返回参数错误。
comm_resource_config.max_active_channels	整数	可选	配置Server设备侧同时活跃传输通道数量。取值为正整数；未配置时默认值为128；取值小于1或非数字时，Server创建失败并返回参数错误。

Client侧global_resource_config当前支持的配置项如下。

配置项	类型	是否必选	描述
comm_resource_config.qos	数字	可选	配置通信协议qos，当前仅支持[0-7]，当未配置的时候，默认为0。
comm_resource_config.max_active_channels	整数	可选	配置Client设备侧同时活跃传输通道数量。取值为正整数；未配置时默认值为128；取值小于1或非数字时，Client创建失败并返回参数错误。

Server配置示例：

{
  "comm_resource_config.listen_port": 26666
}

Client配置示例：

{
  "comm_resource_config.qos": 7
}

HixlClientDesc

Client描述信息。

struct HixlClientDesc {
  const EndpointDesc *local_endpoint;
  const EndpointDesc *remote_endpoint;
  const char *server_ip;
  uint32_t server_port;
  uint8_t tc;
  uint8_t sl;
  uint8_t reserved[98] = {};
};

字段说明：

字段	类型	描述
local_endpoint	const EndpointDesc*	本端Endpoint描述（定义见 https://gitcode.com/cann/hcomm/blob/master/include/hcomm_res_defs.h ）。
remote_endpoint	const EndpointDesc*	远端Endpoint描述（定义见 https://gitcode.com/cann/hcomm/blob/master/include/hcomm_res_defs.h ）。
server_ip	const char*	目标 server Host IP。
server_port	uint32_t	目标 server Host 端口。
tc	uint8_t	RDMA网卡的traffic class。
sl	uint8_t	RDMA网卡的service level。
reserved	uint8_t[98]	HixlClientDesc配置保留字段，用于未来扩展，结构体总大小保持为128字节。

HixlServerDesc

Server 描述信息。

struct HixlServerDesc {
  const EndpointDesc *endpoint_list;
  const char *server_ip;
  uint32_t server_port;
  uint32_t endpoint_list_num;
  uint8_t reserved[104] = {};
};

字段说明：

字段	类型	描述
server_ip	const char*	侦听 IP。
server_port	uint32_t	侦听端口。
endpoint_list	const EndpointDesc*	Endpoint描述数组指针。Endpoint描述定义见 https://gitcode.com/cann/hcomm/blob/master/include/hcomm_res_defs.h
endpoint_list_num	uint32_t	Endpoint数量。
reserved	uint8_t[104]	HixlServerDesc配置保留字段，用于未来扩展，结构体总大小保持为128字节。

HixlOneSideOpDesc

单向操作描述（用于批量put/get）。

struct HixlOneSideOpDesc {
  void *remote_buf;
  void *local_buf;
  uint64_t len;
};

字段说明：

字段	类型	描述
remote_buf	void*	远端（server）数据地址。
local_buf	void*	本端（client）数据地址。
len	uint64_t	传输长度（字节）。

Put 与 Get 对 HixlOneSideOpDesc 的语义：

BatchPut（同步/异步）：数据从 local_buf 拷贝到 remote_buf，长度为 len。
BatchGet（同步/异步）：数据从 remote_buf 拷贝到 local_buf，长度为 len。

枚举

异步任务完成状态定义：

enum HixlCompleteStatus {
  HIXL_COMPLETE_STATUS_WAITING,
  HIXL_COMPLETE_STATUS_COMPLETED,
  HIXL_COMPLETE_STATUS_TIMEOUT,
  HIXL_COMPLETE_STATUS_FAILED
};

说明：其中HIXL_COMPLETE_STATUS_TIMEOUT和HIXL_COMPLETE_STATUS_FAILED当前为预留字段。

接口说明

每个接口包含：函数功能、函数原型、参数说明、返回值、调用示例与约束说明。

HixlCSServerCreate

函数功能

创建并初始化Server实例。

函数原型

HixlStatus HixlCSServerCreate(const HixlServerDesc *server_desc,
                              const HixlServerConfig *config,
                              HixlServerHandle *server_handle);

参数说明

参数名	输入/输出	描述
server_desc	输入	Server 描述信息，包含侦听 IP/端口与端点列表。
config	输入	Server配置，不支持传入NULL；如需配置通信资源监听端口，填写 `HixlServerConfig.global_resource_config`。
server_handle	输出	返回创建的 HixlServerHandle。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败或错误码（见常量）。

约束说明

如果使用本地device的Endpoint，调用该接口前需要先调用“aclrtSetDevice”。
调用失败时server_handle不保证有效。

HixlCSServerRegMem

函数功能

Server注册共享内存供Client访问。

函数原型

HixlStatus HixlCSServerRegMem(HixlServerHandle server_handle,
                              const char *mem_tag,
                              const CommMem *mem,
                              MemHandle *mem_handle);

参数说明

参数名	输入/输出	描述
server_handle	输入	Server 实例句柄。
mem_tag	输入	内存标签字符串，用于标识此内存，可选，可传入为NULL。
mem	输入	指向 CommMem，描述内存位置与大小（定义见 https://gitcode.com/cann/hcomm/blob/master/include/hcomm_res_defs.h ）。
mem_handle	输出	返回的内存句柄，用于后续注销。

返回值

HIXL_SUCCESS：注册成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

在client调用HixlCSClientConnect与本端建链之前需要完成所有本地内存的注册。
使用host RoCE网卡当前不支持注册“aclrtMallocHost”申请出来的内存，可使用malloc等方式。
注册Device内存使用“aclrtMalloc”进行申请。

HixlCSServerListen

函数功能

启动 Server 侦听，接受来自 Client 的连接。

函数原型

HixlStatus HixlCSServerListen(HixlServerHandle server_handle, uint32_t backlog);

参数说明

参数名	输入/输出	描述
server_handle	输入	Server 实例句柄。
backlog	输入	连接队列最大长度。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

在client调用HixlCSClientConnect与本端建链之前需要完成侦听。

HixlCSServerUnregMem

函数功能

注销之前注册的内存。

函数原型

HixlStatus HixlCSServerUnregMem(HixlServerHandle server_handle, MemHandle mem_handle);

参数说明

参数名	输入/输出	描述
server_handle	输入	Server 实例句柄。
mem_handle	输入	需注销的内存句柄（HixlCSServerRegMem 返回）。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

确保远端不再访问该内存后，且与当前server建链的client均断链以后再注销。

HixlCSServerDestroy

函数功能

销毁 Server 实例并释放相关资源。

函数原型

HixlStatus HixlCSServerDestroy(HixlServerHandle server_handle);

参数说明

参数名	输入/输出	描述
server_handle	输入	Server 实例句柄。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

需要和HixlCSServerCreate配对使用。
建议在调用HixlCSServerDestroy前，链路进行断链以及对注册的内存进行解注册。
Server需要等所有Client完成断链后调用该接口，如果Server提前退出，Client断链以及数据传输过程会发生报错。
当Client需要操作Server端地址进行远端读写，Server端需要等Client完成远端读写之后才调用该接口；否则会出现失败。
该接口不能和其他接口并发调用。

HixlCSClientCreate

函数功能

创建 Client 实例并初始化本端资源。

函数原型

HixlStatus HixlCSClientCreate(const HixlClientDesc *client_desc,
                              const HixlClientConfig *config,
                              HixlClientHandle *client_handle);

参数说明

参数名	输入/输出	描述
client_desc	输入	Client 描述，包含 server IP/port 与端点。
config	输入	Client配置，不支持传入NULL；如需配置通信资源参数，填写 `HixlClientConfig.global_resource_config`。
client_handle	输出	返回创建的客户端句柄。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

如果使用本地device的Endpoint，调用该接口前需要先调用“aclrtSetDevice”。
调用失败时 client_handle 不保证有效。

HixlCSClientConnect

函数功能

发起与 Server 的同步建链（阻塞直到成功或超时）。

函数原型

HixlStatus HixlCSClientConnect(HixlClientHandle client_handle, uint32_t timeout_ms);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
timeout_ms	输入	连接超时时间（毫秒）。

返回值

HIXL_SUCCESS：连接成功
HIXL_PARAM_INVALID：参数错误
HIXL_TIMEOUT：连接超时
其他：失败

约束说明

调用当前接口与server建链前，需要完成所有本地内存的注册。
调用当前接口与server建链前，需要确保server已经处于侦听状态。
调用当前接口建链后，需要调用HixlCSClientGetRemoteMem接口，确保远端内存描述信息交换至本地。

HixlCSClientGetRemoteMem

函数功能

获取 Server 已注册的内存信息。

函数原型

HixlStatus HixlCSClientGetRemoteMem(HixlClientHandle client_handle,
                                    CommMem **remote_mem_list,
                                    char ***mem_tag_list,
                                    uint32_t *list_num,
                                    uint32_t timeout_ms);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
remote_mem_list	输出	返回的 `CommMem` 数组指针，内存生命周期由接口内部管理。重复调用该接口，将释放上一次申请的内存，如有需要按需拷贝至本地内存（定义见 https://gitcode.com/cann/hcomm/blob/master/include/hcomm_res_defs.h）。
mem_tag_list	输出	字符串数组，对应每个 `CommMem` 的标签，内存生命周期由接口内部管理。重复调用该接口，将释放上一次申请的内存，如有需要按需拷贝至本地内存。
list_num	输出	返回的列表长度，内存生命周期由接口内部管理。重复调用该接口，将释放上一次申请的内存，如有需要按需拷贝至本地内存。
timeout_ms	输入	请求超时时间（毫秒）。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败或超时

约束说明

输出参数内存生命周期由接口内部管理。重复调用该接口，将释放上一次申请的内存，如有需要按需拷贝至本地内存。
调用HixlCSClientConnect接口后，需要调用当前接口，确保远端内存描述信息交换至本地。

HixlCSClientRegMem

函数功能

Client 注册本地内存。

函数原型

HixlStatus HixlCSClientRegMem(HixlClientHandle client_handle,
                              const char *mem_tag,
                              const CommMem *mem,
                              MemHandle *mem_handle);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
mem_tag	输入	内存标签字符串。
mem	输入	`CommMem` 描述。
mem_handle	输出	返回的内存句柄。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

在调用HixlCSClientConnect与server端建链之前需要完成所有本地内存的注册。
使用host RoCE网卡当前不支持注册“aclrtMallocHost”申请出来的内存，可使用malloc等方式。
注册Device内存使用“aclrtMalloc”进行申请。

HixlCSClientUnregMem

函数功能

注销 Client 注册的内存。

函数原型

HixlStatus HixlCSClientUnregMem(HixlClientHandle client_handle, MemHandle mem_handle);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
mem_handle	输入	要注销的内存句柄。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

确保本地不再访问该内存后，且与server均断链以后再注销。

HixlCSClientBatchPutAsync

函数功能

异步批量向Server写多组数据。

函数原型

HixlStatus HixlCSClientBatchPutAsync(HixlClientHandle client_handle,
                                     uint32_t list_num,
                                     const HixlOneSideOpDesc *desc_list,
                                     CompleteHandle *complete_handle);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
list_num	输入	子任务条数，须大于 0；为 0 时返回 `HIXL_PARAM_INVALID`。
desc_list	输入	指向 `HixlOneSideOpDesc` 数组，长度为 `list_num`；`list_num > 0` 时不可为 NULL。每项为 local_buf → remote_buf，`len` 为字节数。
complete_handle	输出	返回的完成句柄，用于用户异步查询任务状态，当查询成功后，将自动释放相关资源。不可为 NULL。

返回值

HIXL_SUCCESS：任务提交成功（不代表完成）
HIXL_PARAM_INVALID：参数错误
其他：提交失败

约束说明

最大支持4K个数据并发传输，下发任务后需及时调用HixlCSClientQueryCompleteStatus接口查询任务状态。

HixlCSClientBatchGetAsync

函数功能

异步批量从Server读多组数据到本地。

函数原型

HixlStatus HixlCSClientBatchGetAsync(HixlClientHandle client_handle,
                                     uint32_t list_num,
                                     const HixlOneSideOpDesc *desc_list,
                                     CompleteHandle *complete_handle);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
list_num	输入	子任务条数，须大于 0；为 0 时返回 `HIXL_PARAM_INVALID`。
desc_list	输入	指向 `HixlOneSideOpDesc` 数组，长度为 `list_num`；`list_num > 0` 时不可为 NULL。每项为 remote_buf → local_buf，`len` 为字节数。
complete_handle	输出	返回的完成句柄，用于用户异步查询任务状态，当查询成功后，将自动释放相关资源。不可为 NULL。

返回值

HIXL_SUCCESS：任务提交成功（不代表完成）
HIXL_PARAM_INVALID：参数错误
其他：提交失败

约束说明

最大支持4K个数据并发传输，下发任务后需及时调用HixlCSClientQueryCompleteStatus接口查询任务状态。

HixlCSClientBatchPutSync

函数功能

同步批量向 Server 写入多组数据：在整批传输完成、超时或失败前阻塞当前线程，不返回 CompleteHandle。

函数原型

HixlStatus HixlCSClientBatchPutSync(HixlClientHandle client_handle,
                                    uint32_t list_num,
                                    const HixlOneSideOpDesc *desc_list,
                                    uint32_t timeout_ms);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄，不可为 NULL。
list_num	输入	子任务条数，须大于 0；为 0 时返回 `HIXL_PARAM_INVALID`。
desc_list	输入	长度为 `list_num` 的 `HixlOneSideOpDesc` 数组；`list_num > 0` 时不可为 NULL。数据方向为 local_buf（源）→ remote_buf（目标），`len` 为每次传输的字节数。
timeout_ms	输入	整批任务的总等待超时（毫秒）。超时返回 `HIXL_TIMEOUT`。Host 端实现为轮询等待完成；Device 端为流同步超时预算。

返回值

HIXL_SUCCESS：整批传输已完成
HIXL_PARAM_INVALID：参数错误（如 list_num == 0、desc_list 非法、client_handle 为 NULL 等）
HIXL_TIMEOUT：在 timeout_ms 内未完成
其他：传输或内部错误（见日志与 HixlStatus 码）

约束说明

调用前须已完成与 Server 的建链（如 HixlCSClientConnect），且 desc_list 中的地址须为已注册/已通过 HixlCSClientGetRemoteMem 等途径获得的合法单边访问地址。
与异步接口相同，建议关注最大并发子任务规模等限制（参见异步批量接口说明）。

HixlCSClientBatchGetSync

函数功能

同步批量从 Server 读取多组数据到本地：在整批传输完成、超时或失败前阻塞当前线程，不返回 CompleteHandle。

函数原型

HixlStatus HixlCSClientBatchGetSync(HixlClientHandle client_handle,
                                    uint32_t list_num,
                                    const HixlOneSideOpDesc *desc_list,
                                    uint32_t timeout_ms);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄，不可为 NULL。
list_num	输入	子任务条数，须大于 0；为 0 时返回 `HIXL_PARAM_INVALID`。
desc_list	输入	长度为 `list_num` 的 `HixlOneSideOpDesc` 数组；`list_num > 0` 时不可为 NULL。数据方向为 remote_buf（源）→ local_buf（目标），`len` 为每次传输的字节数。
timeout_ms	输入	整批任务的总等待超时（毫秒）。超时返回 `HIXL_TIMEOUT`。Host 端实现为轮询等待完成；Device 端为流同步超时预算。

返回值

HIXL_SUCCESS：整批传输已完成
HIXL_PARAM_INVALID：参数错误（如 list_num == 0、desc_list 非法、client_handle 为 NULL 等）
HIXL_TIMEOUT：在 timeout_ms 内未完成
其他：传输或内部错误（见日志与 HixlStatus 码）

约束说明

调用前须已完成与 Server 的建链（如 HixlCSClientConnect），且 desc_list 中的地址须为已注册/已通过 HixlCSClientGetRemoteMem 等途径获得的合法单边访问地址。
与异步接口相同，建议关注最大并发子任务规模等限制（参见异步批量接口说明）。

HixlCSClientQueryCompleteStatus

函数功能

查询异步批量任务的完成状态。

函数原型

HixlStatus HixlCSClientQueryCompleteStatus(HixlClientHandle client_handle,
                                           CompleteHandle complete_handle,
                                           HixlCompleteStatus *complete_status);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。
complete_handle	输入	要查询的任务句柄。
complete_status	输出	返回任务状态枚举（见 `HixlCompleteStatus`）。

返回值

HIXL_SUCCESS：查询成功，传输状态需要根据complete_status确定。
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

最大支持4K个数据并发传输，下发任务后需及时调用HixlCSClientQueryCompleteStatus接口查询任务状态。
查询传输任务状态为HIXL_COMPLETE_STATUS_COMPLETED后，相关资源将自动释放，不支持使用相同的complete_handle再次查询。
查询传输任务状态为HIXL_COMPLETE_STATUS_WAITING，需用户自行判断当前传输任务是否已经发生超时，如果超时可重建传输传输链路进行重试，并销毁当前异常链路。

HixlCSClientDestroy

函数功能

销毁 Client 实例并释放资源。

函数原型

HixlStatus HixlCSClientDestroy(HixlClientHandle client_handle);

参数说明

参数名	输入/输出	描述
client_handle	输入	客户端句柄。

返回值

HIXL_SUCCESS：成功
HIXL_PARAM_INVALID：参数错误
其他：失败

约束说明

需要和HixlCSClientCreate配对使用。
建议在调用HixlCSClientDestroy前，链路进行断链以及对注册的内存进行解注册。
该接口不能和其他接口并发调用。

使用建议

环境准备：调用 aclrtSetDevice(device_id)。
准备 Endpoint 描述（EndpointDesc）。
Server 流程：
- 构造 HixlServerDesc 与 HixlServerConfig，如需指定通信资源监听端口或设备侧同时活跃传输通道数量，在 HixlServerConfig.global_resource_config 中配置 comm_resource_config.listen_port 或 comm_resource_config.max_active_channels。
- 调用 HixlCSServerCreate 创建 HixlServerHandle。
- 为要被远端访问的内存分配并准备 CommMem（Host/Device 内存），调用 HixlCSServerRegMem 注册并保存返回的 MemHandle。
- 调用 HixlCSServerListen 开始侦听连接。
- 等待 Client 建链并发起数据传输。
- 传输结束后调用 HixlCSServerUnregMem 注销内存并 HixlCSServerDestroy 销毁服务。
Client 流程：
- 构造 HixlClientDesc 与 HixlClientConfig，如需指定QoS或设备侧同时活跃传输通道数量，在 HixlClientConfig.global_resource_config 中配置 comm_resource_config.qos 或 comm_resource_config.max_active_channels。
- 调用 HixlCSClientCreate 创建 HixlClientHandle。
- 准备本端 CommMem 并通过 HixlCSClientRegMem 注册（保存 MemHandle）。
- 调用 HixlCSClientConnect 建链（阻塞或等待超时），确保Server处于侦听状态。
- 调用 HixlCSClientGetRemoteMem 获取 Server 已注册的内存，从而获取远端地址用于后续操作。
- 构造一组 HixlOneSideOpDesc（local/remote 地址、长度），任选其一：
  - 调用 HixlCSClientBatchPutAsync / HixlCSClientBatchGetAsync 提交异步批量操作，并轮询 HixlCSClientQueryCompleteStatus 直到状态为 HIXL_COMPLETE_STATUS_COMPLETED；
  - 或调用 HixlCSClientBatchPutSync / HixlCSClientBatchGetSync 同步完成整批传输（需传入整批超时时间 timeout_ms）。
- 完成后按需读取/校验内存内容，最后 HixlCSClientUnregMem 注销本端内存并 HixlCSClientDestroy。

示例

下面给出简化版的流程代码片段，体现基准程序中的关键步骤与顺序（省略细节错误处理与平台初始化代码）：

// --- Server (伪代码) ---
HixlServerHandle server = NULL;
HixlServerDesc sdesc = {};
HixlServerConfig sconfig = {};
sconfig.global_resource_config = "{\"comm_resource_config.listen_port\":26666}";
sdesc.endpoint_list = &endpoint;
sdesc.server_ip = "0.0.0.0";
sdesc.server_port = 12345;
sdesc.endpoint_list_num = 1;
HixlCSServerCreate(&sdesc, &sconfig, &server);

// 分配并初始化 server 内存（Host 或 Device）
CommMem server_mem = { .addr = server_buf, .size = size, .type = COMM_MEM_TYPE_DEVICE };
MemHandle server_mem_h = NULL;
HixlCSServerRegMem(server, "server_mem", &server_mem, &server_mem_h);

HixlCSServerListen(server, 1024);

// 等待 client 发起并完成传输（可用 TCP 信令同步）

// 注销并销毁
HixlCSServerUnregMem(server, server_mem_h);
HixlCSServerDestroy(server);

// --- Client (伪代码) ---
HixlClientHandle client = NULL;
HixlClientDesc cdesc = {};
cdesc.local_endpoint = &local_ep;
cdesc.remote_endpoint = &remote_ep;
cdesc.server_ip = "server.ip";
cdesc.server_port = 12345;
HixlClientConfig cconfig = {};
cconfig.global_resource_config = "{\"comm_resource_config.qos\":7}";
HixlCSClientCreate(&cdesc, &cconfig, &client);

// 分配并注册本地内存
CommMem client_mem = { .addr = client_buf, .size = size, .type = COMM_MEM_TYPE_DEVICE };
MemHandle client_mem_h = NULL;
HixlCSClientRegMem(client, "client_mem", &client_mem, &client_mem_h);

// 建链
HixlCSClientConnect(client, 5000);

// 获取远端内存地址（通过 mem_tag）
CommMem *remote_list = NULL; char **tags = NULL; uint32_t num = 0;
HixlCSClientGetRemoteMem(client, &remote_list, &tags, &num, 2000);

// 构造批量操作描述，示例：分块循环 varying block size
std::vector<HixlOneSideOpDesc> ops = ...; // 填写 local/remote addr 与 len

// 方式一：异步 + 轮询完成
CompleteHandle ch;
HixlCSClientBatchPutAsync(client, ops.size(), ops.data(), &ch);
HixlCompleteStatus st;
do {
  HixlCSClientQueryCompleteStatus(client, ch, &st);
  std::this_thread::sleep_for(std::chrono::milliseconds(1));
} while (st == HIXL_COMPLETE_STATUS_WAITING);

// 方式二：同步（整批在 timeout 内完成则返回 HIXL_SUCCESS）
// HixlCSClientBatchPutSync(client, ops.size(), ops.data(), 5000);

// 清理
HixlCSClientUnregMem(client, client_mem_h);
HixlCSClientDestroy(client);