Ownership

Every execution unit and resource in Nexphant has a deterministic owner. When an owner completes or is closed, the runtime automatically cleans up and releases all resources associated with that owner, preventing memory leaks and resource exhaustion in long-running processes.

The Concept of Runtime Owners

An owner is represented by the RuntimeOwner class. Each owner possesses:

• A unique OwnerId UUID.
• An OwnerType categorizing the execution context.
• An optional parent OwnerId establishing a hierarchical tree.
• Metadata and lifecycle timestamps (createdAt, closedAt, duration()).

All active owners are tracked globally by the singleton OwnerRegistry.

Owner Types

The OwnerType enum supports the following execution context types:

Enum Case	Value	Description
SYSTEM	'system'	The base runtime system context.
WORKER	'worker'	Long-lived persistent worker process context.
REQUEST	'request'	HTTP Request handling context.
FIBER	'fiber'	Asynchronous coroutine/fiber execution context.
QUEUE_JOB	'queue_job'	Background queue job handler context.
TIMER	'timer'	Event loop timer execution context.
SCHEDULER_TASK	'scheduler_task'	Scheduled task execution context.
RESOURCE	'resource'	Explicit wrapper context for complex system resources.
EXECUTOR_TASK	'executor_task'	Bounded executor task execution unit.

Scoped Ownership using withOwner()

The recommended way to execute code under a specific owner is using Runtime::withOwner(). This method opens an owner, sets the execution context, runs the callable, and ensures the owner is safely closed afterwards:

use Nexphant\Runtime\Runtime;
use Nexphant\Core\Ownership\OwnerType;

$result = Runtime::withOwner(OwnerType::FIBER, function () {
    // Current owner ID is automatically updated in the Runtime context
    $ownerId = Runtime::owner();
    
    // Acquire resources here; they are now bound to this Owner
    $resource = acquireSomeResource();
    
    return $result;
}, ['custom_meta' => 'value']);

// The fiber owner has closed here, and all bound resources are automatically released!

Hierarchical Owner Tree

Owners can be nested under parent owners. When a parent owner is closed, the OwnerRegistry recursively closes all of its children:

WORKER (Root)
└── REQUEST (Parent)
    ├── FIBER (Child)
    │   └── TIMER (Grandchild)
    └── FIBER (Child)

Closing the REQUEST parent owner will automatically:

1. Signal closure to FIBER children.
2. Recursively signal closure to TIMER grandchildren.
3. Automatically release all resources tracked under these owners with the reason parent_closed.

Behind the Scenes: OwnerRegistry API

For low-level tracking, you can interact directly with the OwnerRegistry via Runtime::owners():

use Nexphant\Runtime\Runtime;
use Nexphant\Core\Ownership\OwnerType;

$registry = Runtime::owners();

// Open a new owner manually
$owner = $registry->open(
    OwnerType::QUEUE_JOB, 
    $parentOwnerId, 
    ['job_name' => 'SendWelcomeEmail']
);

try {
    // Execute job operations
} finally {
    // Close the owner, releasing its associated resources
    $registry->close($owner->id(), 'job_finished');
}

Related Guides

• Resource Lifecycle
• Context
• Cancellation & Deadline