ErisPulse.Core.ownership 模块
模块概述
ErisPulse 归属权统一门面
归属权(owner)系统对外的统一入口。框架各子系统(路由 / 处理器 / 命令 / 任务 / 覆写 / 生命周期 / 主人身份源……)各自维护按 owner 注册的资源, 本模块把它们聚合为四个动词,替代散落在各子系统上形态不一的清理与查询 API:
- :func:
ownership.reclaim/ :func:ownership.reclaim_sync—— 统一注销 owner 名下的全部资源(模块卸载 / 禁用 / 失败回滚共用的回收路径) - :func:
ownership.counts—— 按 owner 统计在册资源(审计的计数面) - :func:
ownership.orphans—— 孤儿扫描:资源在册而 owner 已注销(泄漏实锤) - :func:
ownership.audit—— 泄漏审计(计数 + 孤儿 + 可选 gc 实例普查) - :func:
ownership.nest/ :func:ownership.unnest—— 声明父子归属, 父回收时按注册逆序先回收子(资源级,不触发子的模块级on_unload)
各子系统既有的 *_by_owner 注销函数保持不变,作为本门面的内部 SPI;
新增可回收资源时,子系统提供注销函数并登记进 :func:reclaim_sync 的
步骤表、在 :func:counts 提供只读计数,门面与审计器即自动覆盖。
提示
- reclaim 的注销顺序固定(归属任务 / 外部清理钩子先行,注册类资源随后), 每步独立容错——单步失败不阻断其余回收(与卸载流程兜底风格一致)
- counts / orphans 只读,无任何清理副作用
- audit(deep=True) 会
gc.collect()并做 weakref 实例存活普查——存在 全局暂停开销,仅显式调用(epsdk audit --deep)
函数列表
_log_reclaim_failure(step: str, error: Exception) -> None
内部方法 回收步骤失败留痕(单步失败不阻断其余回收,但必须可观测)
类列表
class OwnershipManager
归属权管理器(单例)
聚合各子系统的 owner 归属资源:统一注销(reclaim)、只读计数(counts)、
孤儿扫描(orphans)、泄漏审计(audit)、嵌套生命周期(nest / unnest),
以及影子 owner 判定面(is_shadow / register_shadow / unregister_shadow——
影子模块机制,见 Core/shadow 与 docs/zh-CN/advanced/shadow.md)。
子系统内部表通过惰性导入访问,避免加载链耦合(与 module.py 清理链的
既有风格一致)。
方法列表
nest(parent: str, child: str) -> bool
声明父子归属关系:父被回收时子先被完整回收
拒绝自环与已存在的反向链(会形成环);重复声明幂等。
- parent: 父 owner 名
- child: 子 owner 名
返回值: 是否声明成功
示例:
from ErisPulse.Core import ownership
ownership.nest("ScriptEngine", "ScriptEngine.plugin_a")
True
unnest(parent: str, child: str) -> bool
解除父子归属关系
- parent: 父 owner 名
- child: 子 owner 名
返回值: 是否解除了既有关系
nested_children(parent: str) -> 'frozenset[str]'
只读视图:父 owner 当前登记的子 owner
- parent: 父 owner 名
返回值: 子 owner 名集合
begin_nested_reclaim(owner: str) -> bool
内部方法 标记 owner 的异步级联回收即将开始
供同步入口(如 ModuleManager.disable)在调度后台级联前调用,
使随后的 :meth:reclaim_sync 跳过子级联,避免与异步路径重复。
- owner: 父 owner 名
返回值: 是否存在需要级联的子 owner
async reclaim_nested(owner: str) -> 'dict[str, int]'
按注册逆序回收 owner 的全部子 owner(递归级联)
每个子回收受 CLEANUP_CALLBACK_TIMEOUT_SECS 约束;超时或失败
告警后继续处理其余子,并移除该父子关系(残留资源由 orphans 暴露)。
- owner: 父 owner 名
返回值: {"nested_children": 已处理子数}
_reaches(start: str, target: str) -> bool
内部方法 沿子关系判断 start 是否可达 target(环检测)
_detach_from_parents(child: str) -> None
内部方法 子被独立回收后从所有父的登记中移除
register_shadow(owner: str) -> None
登记影子 owner(ShadowManager 装配影子模块时调用)
- owner: 影子 owner 名(如
"roll_shadow")
unregister_shadow(owner: str) -> None
移除影子 owner 登记(影子转正 / 放弃时调用)
- owner: 影子 owner 名
is_shadow(owner: 'str | None') -> bool
判定 owner 是否为影子模块 owner(八道隔离闸的统一判定入口)
- owner (
owner): 名
返回值: 是否为已登记的影子 owner
shadow_owners() -> 'frozenset[str]'
当前全部影子 owner(只读视图)
返回值: 影子 owner 名集合
async reclaim(owner: str) -> 'dict[str, int]'
统一注销 owner 名下的全部资源(异步完整版)
顺序:取消归属后台任务 → 关闭归属连接 → 释放合作式登记资源 → 触发外部清理钩子(on_cleanup)→ 注销全部注册类资源。模块卸载 / 禁用的标准回收路径。
- owner (
owner): 名(模块名或适配器平台名)
返回值: 各类资源注销数量(键见 :meth:reclaim_sync,另含
``tasks_cancelled`` / ``cleanups_run``)
示例:
from ErisPulse.Core import ownership
await ownership.reclaim("roll")
async reclaim_tasks(owner: str) -> 'dict[str, int]'
注销 owner 的进行中工作:归属后台任务取消 + 归属连接关闭 + 合作式资源释放 + 外部清理钩子触发
- owner (
owner): 名
返回值: {"tasks_cancelled": int, "connections_closed": int,
"tracked_released": int, "cleanups_run": int}
reclaim_sync(owner: str) -> 'dict[str, int]'
注销 owner 的全部注册类资源(同步版,不含任务取消)
涵盖:i18n 翻译域、路由(命名空间 + owner 兜底)、适配器事件处理器、 自定义会话类型、平台事件方法注入、事件覆写、scope 覆写、命令与 四类事件处理器、交互会话等待、主人身份源、生命周期钩子、 日志订阅(logger.handler)、对话恢复工厂(resume handler)。 每步独立容错,单步失败不阻断后续回收。
- owner (
owner): 名(模块名或适配器平台名)
返回值: 各类资源注销数量
示例:
ownership.reclaim_sync("roll")
{"routes_http": 2, "commands": 1, ...}
counts(owner: 'str | None' = None) -> Any
统计 owner 在册的归属资源(只读,无副作用)
- owner (
owner): 名;None 时返回全部 owner 的计数
返回值: owner 给定时为 {资源类: 数量};None 时为
{owner: {资源类: 数量}}(未挂任何资源的 owner 不出现)
示例:
ownership.counts("roll")
{"commands": 1, "lifecycle_hooks": 2}
orphans() -> 'list[dict[str, Any]]'
孤儿 owner 扫描:资源仍在册、而 owner(模块 / 适配器)已注销
这是资源泄漏的实锤信号——清理链对"有注册存根的 owner"生效, 孤儿资源(如工具模块私有容器持有的句柄、第三方库内部的引用) 框架无法自动回收,但本扫描让它们可见。
返回值 ({"owner": str, "total": int, "resources": {资源类: 数量}}, ...):
按 owner 名排序;无孤儿时为空列表
示例:
from ErisPulse.Core import ownership
ownership.orphans()
[{"owner": "ghost_module", "total": 2, "resources": {"commands": 1, ...}}]
audit(owner: 'str | None' = None, deep: bool = False) -> 'dict[str, Any]'
泄漏审计:计数 + 孤儿扫描(+ 可选 gc 实例普查)
owner: 目标 owner(模块名);None 时审计全局(全部 owner 计数)
deep: 对模块实例做 weakref 存活普查——
gc.collect()后检查实例是否可回收,不可回收时给出引用方类型(有全局暂停 开销,仅显式使用)
返回值: 审计报告 dict(owner / counts / orphans / 深普查结果)
示例:
ownership.audit("roll", deep=True)
{"owner": "roll", "counts": {...}, "orphans": [], "instance_recyclable": True}