【合入来源】

如有社区issue，请关联issue链接
请勿携带内部流程信息（需求链接、问题单、内部issue等）

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

【修改方案】

目标模块 / Feature： MemPool 析构与指定池内存释放
该改动的核心目标是：实现 MemPool 对象析构时自动释放其关联的内存池资源，解决 MemPool 缺少析构函数导致的内存泄漏问题。

1. feature 核心工作机制

该改动实现了 MemPool 的 RAII 析构机制：

• MemPool 构造时：记录当前设备索引 device_，生成唯一池 ID id_
• MemPool 析构时：调用 releasePool(device_, id_) 减少引用计数并标记可释放，再调用 emptyCache(id_) 精确释放该池的缓存内存
• emptyCache 扩展：新增 mempool_id 参数，支持只释放指定池的缓存，避免影响其他池
• synchronize_and_free_events 扩展：新增 pool 过滤参数，支持只同步特定池的事件，减少不必要的同步开销
• graph_pool_handle 静态化：将池 ID 生成逻辑提取为静态方法，避免创建临时 MemPool 对象：该步骤目的是保证修改前后graph行为一致，且与社区行为一致。如果NPUGraph中仍然使用临时MemPool，会由于新增的析构函数导致多次releasePool，这样导致TORCH_INTERNAL_ASSERT(it != graph_pools.end());报错

2. 核心调用路径

MemPool::~MemPool()
  → NPUCachingAllocator::releasePool(device_, id_)     // 引用计数管理
    → DeviceCachingAllocator::releasePool(mempool_id)
      → use_count-- → 插入 graph_pools_freeable
  → NPUCachingAllocator::emptyCache(id_)               // 缓存释放
    → NPUCachingAllocator::emptyCache(check_error, free_physical, mempool_id)
      → DeviceCachingAllocator::emptyCache(..., mempool_id)
        → release_cached_blocks(..., mempool_id)
          → synchronize_and_free_events(..., pool)      // 只同步该池事件
          → release_blocks(small_blocks/large_blocks)   // 释放该池缓存块
          → graph_pools.erase (若 npuMalloc_count==0)

3. 核心数据结构

• MemPool：新增 device_ 成员（c10::DeviceIndex），新增析构函数、device() 方法、graph_pool_handle() 静态方法
• MempoolId_t：std::pair<CaptureId_t, CaptureId_t>，{0,0} 表示"未指定池"
• PrivatePool：持有 use_count（图引用计数）和 npuMalloc_count（未释放分配数）
• graph_pools_freeable：ska::flat_hash_map<MempoolId_t, PrivatePool*>，记录可释放的池

4. 推荐阅读顺序

1. torch_npu/csrc/core/npu/NPUCachingAllocator.h:563-603 — MemPool 类定义，理解新增接口
2. torch_npu/csrc/core/npu/NPUCachingAllocator.cpp:3997-4022 — MemPool 析构函数、device()、graph_pool_handle() 实现
3. torch_npu/csrc/core/npu/NPUCachingAllocator.cpp:2181-2212 — releasePool 引用计数管理
4. torch_npu/csrc/core/npu/NPUCachingAllocator.cpp:1643-1665 — emptyCache 设备级实现
5. torch_npu/csrc/core/npu/NPUCachingAllocator.cpp:2810-2848 — release_cached_blocks 指定池释放
6. torch_npu/csrc/core/npu/NPUCachingAllocator.cpp:3000-3048 — synchronize_and_free_events 池过滤
7. torch_npu/csrc/core/npu/NPUGraph.cpp:42-47 — graph_pool_handle() 改用静态方法
8. test/npu/test_mempool_destructor.py — 测试用例

5. 可能存在的API一致性以及ABI兼容性问题

1. vtable 布局变化：NPUAllocator 基类新增虚函数 emptyCache(bool, bool, MempoolId_t)，所有继承该基类的第三方代码需重新编译
2. MemPool 类大小变化：新增 device_ 成员改变了 sizeof(MemPool)，直接操作 MemPool 对象的已编译代码需重新编译
3. Python 绑定不完整（涉及到api，当前需求暂不做该步骤，后续社区一致性需求补齐）：新增的 device() 和 graph_pool_handle() 方法未绑定到 Python，Python 用户无法调用
4. NPUPluggableAllocator 不支持（cuda带mempool_id的行为与不带mempool_id行为一致，所以暂时无需支持）：带 mempool_id 的 emptyCache 仅打印警告，使用可插拔分配器时 MemPool 析构不会释放内存
5. Python 侧 empty_cache 未暴露 mempool_id（涉及到api，当前需求暂不做该步骤，后续社区一致性需求补齐）：torch.npu.empty_cache() 仍只调用无参版本，用户无法从 Python 手动释放指定池的缓存

6、注意特性：

1、torch_npu/csrc/npu/MemPool.cpp ： 参考cuda，pyblind过程初始化npu。解决mempool初始化未识别device的问题
2、torch_npu/csrc/core/npu/NPUCachingAllocator.cpp： 参考cuda，新增createOrIncrefPool
3、torch_npu/npu/memory.py ：参考cuda，新增torch_npu._C._npu_releasePool(device_index, pool.id)，解决第2点会带来use_count+1的问题

【资料变更】

不涉及

【接口变更】

不涉及

【功能验证】

新增ut，库上为去掉print的版本：
优化前：

优化后：

【CheckList】

PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
• PR持续集成流水线（CI）执行通过，代码检查无异常