blob: 8126820d9751e2ce1165eedea0ad3aef9272e1fb (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
#pragma once
#include "Api.h"
#include "ObjectManager.h"
/**
* @file LifecycleManager.h
* @brief Declares monitoring, pinning, cleanup, and contention operations.
*/
namespace nt
{
/**
* @brief 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 views
* referencing 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.
*/
class NT_API LifecycleManager
{
public:
/**
* @brief 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.
*
* @param object Object to monitor.
*/
void Monitor(ObjectManager::registry* object);
/**
* @brief 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.
*
* @param object Object to stop monitoring.
*/
void Unmonitor(ObjectManager::registry* object);
/**
* @brief 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 a view 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.
*
* @param object Object being depended upon.
*/
void Pin(ObjectManager::registry* object);
/**
* @brief 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.
*
* @param object Object whose dependency is being released.
*/
void Unpin(ObjectManager::registry* object);
/**
* @brief 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.
*
* @param object Object to check for contention.
* @return True when the operation may proceed.
*/
const bool Contention(ObjectManager::registry* object);
};
}
|
