ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

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 提供只读计数,门面与审计器即自动覆盖。

提示

  1. reclaim 的注销顺序固定(归属任务 / 外部清理钩子先行,注册类资源随后), 每步独立容错——单步失败不阻断其余回收(与卸载流程兜底风格一致)
  2. counts / orphans 只读,无任何清理副作用
  3. 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}