Ownership (owner) System

Ownership is the cornerstone of the "plug-and-play" nature of modules: all framework resources registered during module loading are automatically attributed, and automatically reclaimed when the module is unloaded or disabled. Module authors only need to declare resources, without writing manual cleanup logic.

Related Systems: Scope determines "whether a resource is active" during event dispatching, while ownership determines "who owns the resource and who is responsible for reclaiming it during lifecycle events." For more details on scope, see Unified Control Plane (scope). For background tasks, see [Lifecycle Management](lifecycle.md#Background Task Ownership and Automatic Cancellation).

{!--< tips >!--}

1. Ownership is automatically recorded at the moment of registration based on current_owner, requiring zero code changes from the module.
2. Unload and disable share the same cleanup chain (_cleanup_module_registrations), where each step only logs a warning if it fails, without interrupting the process.
3. Resources with user-configured semantics (persistent overrides / scope rules / command ACLs) are not cleaned up when the module is unloaded.
4. External handles managed by utility modules can be attached to the cleanup chain via on_cleanup(cb), which will be automatically called when the dependent module is unloaded (see Guide to Utility Modules: Managing Handles of Other Modules). {!--< /tips >!--}

Owner Context Mechanism

The owner is passed through the context variable current_owner (ErisPulse.runtime.context):

from ErisPulse.runtime import owner_scope, get_current_owner

with owner_scope("MyModule"):
    # All resources registered within this context are automatically attributed to MyModule
    assert get_current_owner() == "MyModule"

The framework automatically injects the owner at the following points (module/adapter code does not need to manually wrap these):

Re-injection during execution means that command handlers declared in on_load will still be automatically attributed to the module if they call registration APIs (such as sdk.adapter.on() or overrides.*.set(persist=False)) during runtime.

Resource Ownership Overview

All resources registered by a module within its loading context are recorded for ownership and automatically reclaimed upon unloading/disabling:

On the adapter side, corresponding resources (with platform name as owner) are reclaimed by _cleanup_adapter_resources during the adapter's shutdown() / restart(), including:

Unload/Disable Cleanup Sequence

unload() and disable() share the same cleanup chain (each step is independently wrapped in try/except, failures are only logged, not interrupting subsequent cleanup):

flowchart TD
    A["unload / disable"] --> B["on_unload()（timeout protection）"]
    B --> C["Fallback: cancel background tasks (cancel_owner_tasks）"]
    C --> C1["External ownership cleanup hooks<br/>（registered by tool modules via on_cleanup, triggered by run_owner_cleanups）"]
    C1 --> D["_cleanup_module_registrations<br/>＝ ownership.reclaim_sync()"]
    D --> D1["i18n translation domains"]
    D1 --> D2["Routes: namespace + owner fallback<br/>（exact deletion by route object identity,<br/>including middleware / home entry）"]
    D2 --> D3["Adapter event handlers / middleware"]
    D3 --> D4["Commands + event handlers"]
    D4 --> D5["Custom session types"]
    D5 --> D5b["Platform event method injection"]
    D5b --> D6["Runtime event overwrites (persist=False）"]
    D6 --> D7["Owner source provider"]
    D7 --> D8["Lifecycle hooks"]
    D8 --> E["Remove SDK attributes + lazy-loaded proxies"]
    E --> F["Auto-light audit: orphan owner warnings"]

sdk.uninit() performs additional global fallback on exit: all adapters shutdown → all modules unload → router.stop() (clear routes/middleware/home entry) → cancel_all_background_tasks() → clear event handlers and hooks.

Ownership Facade (ownership)

The sixteen steps of chain cleanup converge under the ownership facade ErisPulse.Core.ownership, with four verbs covering "reclaim, count, scan, audit"—the subsystem-specific *_by_owner reclaim functions remain unchanged, serving as internal implementations of the facade:

from ErisPulse.Core import ownership

ownership.reclaim_sync("MyModule")       # {'commands': 1, 'routes_http': 2, ...}
ownership.counts("MyModule")             # Count of registered resources
ownership.orphans()                      # [{"owner": "ghost", "total": 2, ...}]

Audit entry points:

• Automatic light audit after unload/reload: issues WARNING alert when orphaned owner resources are found (zero-cost counting scan)
• sdk.module.audit(name, deep=True): Module instance gc survey—when an instance is unreclaimable, it reports the referencing type (identifying "who is holding the old instance"); involves global pause overhead, used only for explicit troubleshooting
• Deep survey is an explicit operation, not configurable, and does not perform automatic repair

Hot Reload Failure Rollback

Hot reload has been changed to "Snapshot before Unload → Automatic Rollback on Failure": When a new version encounters syntax errors, missing dependencies, or fails to load, the old instance and its registration status (registry entries, sdk attributes, sys.modules entries) are automatically restored, ensuring uninterrupted service. The log will indicate "Rolled back to old instance to continue service."

Best-effort semantics (documented boundaries):

• Side effects already executed in on_unload (such as disconnected connections, canceled tasks) are irreversible—after rollback, the old instance is in a "cleaned-up" state and must be reloaded to become fully available again.
• Manual references to the old instance cached by third-party libraries during runtime are not restored.
• If the target package has been unloaded (entry-point disappeared), it is considered a successful unload and no rollback will occur.

Design Boundaries: Resources Not Cleaned on Unload

Ownership only recovers runtime resources registered by module code. The following resources are user-configured semantics (controlled by the user, possibly intentionally configured), and persist after module unload:

Runtime temporary writes (persist=False) are reclaimed by owner—persistence is the boundary between "user assets" and "module runtime state."

Internal Implementation: How Ownership Works

The ownership system consists of two independent chains. Understanding their division of labor is essential for troubleshooting ownership issues:

Attribution Chain (contextvar Propagation)

The ContextVars in runtime/context.py, such as current_owner, are responsible for attribution — "whom does the resource registered or the call initiated by the code at this moment belong to?" The propagation rules follow the semantics of Python's contextvars:

Attribution ≠ Registration: Context propagation only affects "to whom it is attributed." Whether the resource is cleaned up depends on whether it enters the subsequent cancellation chain.

Cancellation Chain (Task Registry)

The _owner_tasks registry in runtime/tasks.py manages lifecycle — "which unfinished tasks belong to the owner, and cancel them all together during unload." Tasks enter the registry through:

1. Explicit Scheduling: spawn_background() / self.spawn() → captures current_owner at creation (or explicitly via owner= parameter) → registers into the table;
2. Task Factory Automatic Registration (2.8.3): install_owner_task_factory() is installed into the main event loop at framework startup — any task creation (including create_task inside third-party libraries) is processed by the factory, reading current_owner; if not None, it registers.

Registry self-cleans: Each task includes a done_callback, and once completed, it is removed from the table, preventing leaks.

Cancellation Timing (Module Unload)

module.unload()
  → on_unload(event)                    # Module self-cleans (fallback timeout protection)
  → Framework deregisters commands/events/hooks/routes for this owner
  → cancel_owner_tasks(owner)           # Registry fallback cancellation
      → cancel each task.cancel()       # Excludes the task itself executing cancellation logic
      → await gather(pending, timeout)  # Wait for cleanup (no blocking after timeout)

Troubleshooting Approach

• Resources not cleaned up → Check the registry: get_owner_tasks("MyModule") whether it contains the task; if not, the registration path did not pass through the ownership chain (import phase / thread / independent loop), refer to the table above for identification.
• Incorrect attribution → Check the value of get_current_owner() at the time of error; for asynchronously delayed execution (callbacks/tasks), attribution is taken from the context at creation, not at execution time.

Module Author Guide

Recommended Practices

from ErisPulse import sdk
from ErisPulse.Core.Event import command
from ErisPulse.runtime import owner_scope, spawn_background

class MyModule(BaseModule):
    async def on_load(self, event):
        # Framework resources: automatically owned, no manual cleanup required
        self.task = self.spawn(self.polling())      # Background task
        sdk.router.register_home_entry("My Module", "/my")  # Home entry

        # Module-specific resources: include in owner_scope to integrate into ownership system
        with owner_scope("MyModule"):
            self.client.on_event(self._handle)      # Hypothetical custom registration

    async def on_unload(self, event):
        # Framework resources have been automatically cleaned up, only clean up non-owner_scope covered resources
        await self.client.close()

Notes

• Registration during import has no ownership: Hooks/handlers registered at the module's top level (during import) occur before owner_scope, and are considered framework-level resources (owner=None) and will not be cleaned up. Always register inside on_load().
• Custom domain i18n registration: When i18n.register(domain=...) uses a domain different from the module name, it won't be automatically cleaned up. Please ensure domain=module name.
• Background tasks recommended via self.spawn(): As of 2.8.3, raw asyncio.create_task will also automatically register ownership (Task Factory automatically registers, cancels on unload as a fallback). However, self.spawn() remains the recommended approach—supporting non-main loop thread scheduling back to the main loop, explicit owner= assignment, and fire-and-forget to prevent GC. For versions before 2.8.3, raw tasks are not owned, and self.spawn() must be used.
• Cleanup chain "failure only logs warning": Single-step cleanup exceptions will not block other resource releases, visible in DEBUG/WARNING log levels; enable TRACE for troubleshooting.

Registration Timing → Ownership Result Comparison Table

Principle: Ownership follows the current_owner context at the moment of registration; any asynchronous delay, thread pools, or independent loops will detach from this context—explicitly enter owner_scope when ownership is required.

Tool Module Guide: Handling References to Other Modules

Scenario: Tool modules such as scheduled tasks, registries, and connection pools hold references to other modules—when a module calls sdk.Cron.on_trigger(handler) in its on_load, your container stores a callback pointing to the instance of the calling module. The framework automatically cleans up all framework-level resources registered by the module, but it cannot clean up references stored in your private container: after the module is unloaded, your container still holds its instance, preventing it from being garbage collected (memory leak, purge leak diagnostics report "un回收able").

Solution: In the same function where you register the other module's resources, call on_cleanup(). The framework will automatically invoke your cleanup function when the module is unloaded or disabled:

from ErisPulse.Core.Bases import BaseModule
from ErisPulse.runtime import off_cleanup, on_cleanup

class CronModule(BaseModule):
    def __init__(self):
        self._entries = {}  # {module_name: list of callbacks registered by the module}

    def on_trigger(self, handler):
        # Automatically identifies the caller module name (whether called directly in on_load or via module.call),
        # returns the resolved owner, which can be used directly as a named key
        owner = on_cleanup(self._drop)
        self._entries.setdefault(owner, []).append(handler)

    def _drop(self, owner: str):
        """Called automatically by the framework when the module is unloaded/disabled: simply discard its handle"""
        self._entries.pop(owner, None)

    async def on_unload(self, event):
        off_cleanup(self._drop)  # ③ Unregister the hook before self-unloading to avoid the hook table holding a reference to self

Guaranteed framework behavior:

When Not Needed: If the module registers framework-level resources (commands, event handlers, routes, background tasks, etc.), the framework automatically cleans them up (see Resource Ownership Overview above). Only references held in your private container require on_cleanup. A quick-reference version from a module developer's perspective is available at Best Practices · Tool Modules.