多实例支持

概述

SHMEM 多实例能力允许在单个进程内创建多个独立 SHMEM 实例。每个实例拥有独立的通信域、内存空间和同步资源，适用于以下场景：

多通信域共存：单个进程中多个任务域需要独立 SHMEM 上下文
资源隔离：不同任务/模块之间隔离 SHMEM 资源，避免相互干扰
弹性扩缩：不同实例创建/释放互不影响
动态实例管理：运行时按 instance_id 创建/释放实例

核心概念

实例（Instance）

一个 SHMEM 实例包含一组完整初始化状态，典型包括：

独立的通信域（Team World）
独立的共享内存堆（Heap）
独立的同步资源（Sync Pool/Counter）
独立的 State/Bootstrap/MemoryManager 运行时快照

实例标识（Instance ID）

当前仓库使用 instance_id（uint64_t）标识实例。实例生命周期由初始化属性和 finalize 接口管理。

Context 切换

SHMEM 通过全局变量 swap 机制完成实例切换：切换时先回写当前实例的全局状态，再装载目标实例的全局状态。

架构设计

┌─────────────────────────────────────────────────────────┐
│                     单进程 (Process)                     │
│  ┌───────────────────────────────────────────────────┐  │
│  │              SHMEM Runtime (全局)                  │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │  │
│  │  │  Instance 0 │  │  Instance 1 │  │  Instance N│ │  │
│  │  │  ┌───────┐  │  │  ┌───────┐  │  │  ┌──────┐ │  │  │
│  │  │  │ Team  │  │  │  │ Team  │  │  │  │ Team │ │  │  │
│  │  │  │ Heap  │  │  │  │ Heap  │  │  │  │ Heap │ │  │  │
│  │  │  │ Sync  │  │  │  │ Sync  │  │  │  │ Sync │ │  │  │
│  │  │  │ State │  │  │  │ State │  │  │  │ State│ │  │  │
│  │  │  └───────┘  │  │  └───────┘  │  │  └──────┘ │  │  │
│  │  └─────────────┘  └─────────────┘  └───────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

关键设计决策

设计点	当前实现方案	说明
实例隔离	独立 `aclshmem_context` 快照	每个实例保存独立的 `state`、`host_state`、`boot_handle`、`memory_manager` 等
Context 管理	全局变量 swap	通过 `aclshmemx_instance_ctx_set` 切换
实例标识	`instance_id` (`uint64_t`)	位于 `aclshmemx_init_attr_t`，并用于 `aclshmem_finalize(instance_id)`
Device 侧路由	`instance_id << 1`	kernel 侧通过硬编码地址访问对应实例的 `state`

快速上手（当前仓库 API）

1. 创建实例

#include "shmem.h"

aclshmemx_init_attr_t attr;
attr.my_pe = pe_id;
attr.n_pes = pe_size;
attr.local_mem_size = 1024UL * 1024UL * 1024UL;
attr.ip_port = "tcp://x.x.x.x:0"        // 预先置为0,后续会分配
attr.comm_args = nullptr;               // default mode
attr.instance_id = 2;

int ret = aclshmemx_init_attr(ACLSHMEMX_INIT_WITH_DEFAULT, &attr);

2. 切换到目标实例 Context

aclshmemx_instance_ctx_set(2);

// 后续 SHMEM API 均作用于实例 2
void *ptr = aclshmem_malloc(1024);
aclshmem_free(ptr);

3. 获取当前实例

aclshmem_instance_ctx *ctx = aclshmemx_instance_ctx_get();
// 当前主要用于读取 id，其他能力见上一节
uint64_t cur_id = (ctx == nullptr) ? 0 : ctx->id;

4. 释放实例

aclshmem_finalize(2);

也可直接参照examples/multi_instance目录

规格与限制（按代码实现）

项目	规格
`instance_id` 类型	`uint64_t`
默认实例	`instance_id = 0`
PE 上限	`ACLSHMEM_MAX_PES = 16384`
本地内存上限	`ACLSHMEM_MAX_LOCAL_SIZE = 40GB`
非 0 实例 Team 行为	初始化时仅保留 world team 槽位；team split/translate/get_config 等返回 `ACLSHMEM_NOT_SUPPORTED`
`ip_port` 最大长度	`ACLSHMEM_MAX_IP_PORT_LEN = 64`（含结尾 `\0`）
default 多实例端口范围	依赖 `SHMEM_INSTANCE_PORT_RANGE=start:end`
default 端口分配规则	输入端口必须是 `0`；实际端口 = `start_port + instance_id`
default 可用实例 ID 范围	`instance_id <= end_port - start_port`（含边界）

环境变量与运行要求

Kernel侧使用要求

编译时必须类似 add_compile_definitions(MULTI_INSTANCE) 添加 MULTI_INSTANCE 编译宏
多实例使用时必须在算子开头使用 aclshmemx_instance_ctx_set(id) 来指定当前实例
算子执行时可以做实例间切换

default 多实例模式

必须设置 SHMEM_INSTANCE_PORT_RANGE，格式 start:end
初始化属性中的 ip_port 端口必须为 0，例如 (attr.ip_port = "tcp://x.x.x.x:0")

unique id 模式

仍遵循现有 SHMEM_UID_SESSION_ID / SHMEM_UID_SOCK_IFNAME 规则

注意事项

重复创建同一 instance_id 时：会有WARN日志提示并立即返回（不会重复创建）。
aclshmem_finalize(instance_id) 会先切换到目标实例，再执行释放，避免误释放。
实例上下文相关接口路径由互斥锁保护。

与单实例模式对比

特性	单实例模式	多实例模式
初始化标识	默认 `instance_id=0`	`instance_id>0`
资源隔离	全局共享	按实例隔离
上下文切换	不需要	需要 `aclshmemx_instance_ctx_set`
生命周期管理	`aclshmem_finalize()`	`aclshmem_finalize(instance_id)`
Team 高级操作	支持	仅 `instance_id=0` 支持