多实例支持

概述

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`，并用于 `aclshmemx_finalize(instance_id)`
Device 侧路由	`instance_id << 1`	kernel 侧通过硬编码地址访问对应实例的 `state`

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

项目	规格
`instance_id` 类型	`uint64_t`
默认实例	`instance_id = 0`
实例个数上限	`255`
PE 上限	`ACLSHMEM_MAX_PES = 16384`
本地内存上限	`ACLSHMEM_MAX_LOCAL_SIZE = 40GB`
实例共享内存上限	目前为128GB，超过128GB时底层虚拟地址冲突
非 0 实例 Team 行为	初始化时仅保留 world team 槽位；team split/translate/get_config 等返回 `ACLSHMEM_NOT_SUPPORTED`
default 多实例端口分配	依赖环境变量 `SHMEM_INSTANCE_PORT_RANGE=start:end` (start、end由用户自行指定，每个实例用到的实际端口为 `start_port + instance_id`)
通信链路支持	目前仅MTE

环境变量与运行要求

算子侧使用要求

编译时必须类似 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日志提示并立即返回（不会重复创建）。
aclshmemx_finalize(instance_id) 仅在目标实例非当前活动实例时才切换上下文，再执行释放；传入不存在的 instance_id 会返回错误，不会误伤当前活动实例。
aclshmem_finalize() 释放当前活动实例，不会切换上下文；多实例下需配合 aclshmemx_instance_ctx_set 使用，或直接改用 aclshmemx_finalize。
实例上下文相关接口路径由互斥锁保护。

快速上手（当前仓库 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. 释放实例

多实例场景推荐直接使用 aclshmemx_finalize，按 id 释放指定实例（内部会自动切换上下文，无需手动 set）：

aclshmemx_finalize(2);

也可以用标准接口 aclshmem_finalize() 释放当前活动实例（即最近一次 aclshmemx_instance_ctx_set 设置的实例，未 set 过则为 instance 0）。若要用它释放某个特定实例，需先 set 再调用：

aclshmemx_instance_ctx_set(2);
aclshmem_finalize();   // 释放当前活动实例 2

单实例场景下 aclshmem_finalize() 直接释放 instance 0，与历史无参用法完全一致。

5. 完整样例

examples/multi_instance

与单实例模式对比

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