nt::LifecycleManager Class Reference

Manages runtime lifecycle concerns for registry objects. More...

#include <LifecycleManager.h>

Public Member Functions
	LifecycleManager (ObjectManager &objects, IStorageBackend &storage)
	Constructs a LifecycleManager bound to a registry and store.
void	Monitor (ObjectManager::registry *object)
	Starts monitoring an object's lifecycle.
void	Unmonitor (ObjectManager::registry *object)
	Stops monitoring an object.
void	Pin (ObjectManager::registry *object)
	Increments the structural dependency count on an object.
void	Unpin (ObjectManager::registry *object)
	Decrements the structural dependency count on an object.
bool	IsEligibleForGC (ObjectManager::registry *object) const
	Returns true when the object is GC-eligible right now.
bool	Collect (ObjectManager::registry *object)
	Forces a GC attempt on an object without decrementing a counter.
const bool	Contention (ObjectManager::registry *object)
	Serializes contention for changes to mutable reference states.

Detailed Description

Manages runtime lifecycle concerns for registry objects.

Object lifetime is governed by two independent counters in registry_head: handle_count (sessions holding an open handle) and reference_count (structural dependencies such as cursors pinned to a snapshot or ephemeral relations referencing their base relations). An object is eligible for GC only when both reach zero.

Monitor / Unmonitor manage handle_count. Pin / Unpin manage reference_count. See docs/reactos-ob-comparison.md §1.

Constructor & Destructor Documentation

LifecycleManager()

nt::LifecycleManager::LifecycleManager	(	ObjectManager &	objects,
		IStorageBackend &	storage )

Constructs a LifecycleManager bound to a registry and store.

Needs the registry to perform GC: Unmonitor and Unpin call ObjectManager::Unregister once both counters reach zero. Type-specific cleanup (e.g. cascading a Multigroup's pin to its child Relations, or a BranchTree's pin to its child Multigroups) runs inside the lifecycle manager before the entry is spliced out. The storage backend is needed by CascadeBranchTree to page the merkle nodes.

Member Function Documentation

Collect()

bool nt::LifecycleManager::Collect

(

ObjectManager::registry *

object

)

Forces a GC attempt on an object without decrementing a counter.

Runs the same eligibility check, type-specific cascade, and Unregister as Unmonitor / Unpin, but is callable directly. No-op when the object is still referenced (either counter non-zero) or is a named-lifetime type (BRANCH / SESSION).

Used by the session-close path to collect scratch ephemerals that were never session-pinned and whose consuming cursor has already closed, and (later) by the idle reaper to sweep named entries after Unpinning their session-ownership pin.

Parameters

object

Object to attempt to collect.

Returns

True when the object was eligible and collected.

Contention()

const bool nt::LifecycleManager::Contention

(

ObjectManager::registry *

object

)

Serializes contention for changes to mutable reference states.

Immutable objects — relation snapshots, multigroup snapshots, transactions — never raise contention. Two sessions opening the same immutable snapshot simultaneously is always safe; they will produce independent results without conflict.

Contention applies only to mutable reference states: the HEAD of a branch and namespace entries targeted by atomic multi-reference updates. These are the sole mutable pointers in the system. When a session holds a write handle on a HEAD, a second write opener must block or fail.

Todo

Implement: read object_type::exclusive. Return false immediately for non-exclusive objects. For exclusive objects, return false (contention detected) when handle_count > 0 for a write-mode opener. See docs/reactos-ob-comparison.md §6.

Parameters

object

Object to check for contention.

Returns

True when the operation may proceed.

IsEligibleForGC()

bool nt::LifecycleManager::IsEligibleForGC

(

ObjectManager::registry *

object

)

const

Returns true when the object is GC-eligible right now.

Eligibility is the joint condition handle_count == 0 && reference_count == 0. Decrement callers (Unmonitor / Unpin) consult this and, when true, run type-specific cleanup before unregistering.

Monitor()

void nt::LifecycleManager::Monitor

(

ObjectManager::registry *

object

)

Starts monitoring an object's lifecycle.

Increments handle_count on the object's registry_head. Should be called after all authorization checks pass inside HandlerManager::Open.

Parameters

object

Object to monitor.

Pin()

void nt::LifecycleManager::Pin

(

ObjectManager::registry *

object

)

Increments the structural dependency count on an object.

Call when one object takes a dependency on another — for example when a cursor pins an immutable snapshot version, or when an ephemeral relation is registered against its base relations. Prevents GC of the target object while the dependency is live.

Todo

Implement. See docs/reactos-ob-comparison.md §1.

Parameters

object

Object being depended upon.

Unmonitor()

void nt::LifecycleManager::Unmonitor

(

ObjectManager::registry *

object

)

Stops monitoring an object.

Decrements handle_count. When both handle_count and reference_count reach zero, the object becomes eligible for GC.

Todo

Gate GC on both counters reaching zero, not just handle_count. For deferred compaction, enqueue onto a background GC list rather than freeing inline. See docs/reactos-ob-comparison.md §1 and §7.

Parameters

object

Object to stop monitoring.

Unpin()

void nt::LifecycleManager::Unpin

(

ObjectManager::registry *

object

)

Decrements the structural dependency count on an object.

The inverse of Pin. When both reference_count and handle_count reach zero the object becomes eligible for GC.

Todo

Implement. See docs/reactos-ob-comparison.md §1.

Parameters

object

Object whose dependency is being released.

---

The documentation for this class was generated from the following files:

• LifecycleManager.h
• LifecycleManager.cpp