BoundedRetentionQueue Class
Bounds how many recently-retained objects keep their heavyweight data alive. More...
Declaration
Included Headers
Public Constructors Index
| BoundedRetentionQueue (std::size_t capacity) | |
|
Creates a queue that keeps at most capacity unpinned entries retained. More... | |
Public Member Functions Index
| Pin | retain (std::weak_ptr< const void > owner, std::function< void()> release) |
|
Retains owner's data and pins it in use; after the pin drops, the data is kept until capacity newer owners have been retained, then release is called. More... | |
| std::size_t | capacity () const noexcept |
|
The maximum number of unpinned entries kept retained. More... | |
Private Member Functions Index
| void | sweepWhileLocked () |
|
Releases oldest unpinned entries until at most capacity_ remain. Requires mutex_ to be held. More... | |
| void | unpin (const std::shared_ptr< std::atomic< int > > &pins) |
|
Drops one pin and sweeps, releasing entries the drop made evictable. More... | |
Private Member Attributes Index
| std::size_t | capacity_ |
| std::mutex | mutex_ |
| std::deque< Entry > | entries_ |
Description
Bounds how many recently-retained objects keep their heavyweight data alive.
A FIFO of type-erased entries, each pairing an owner handle with a release callback. When more than capacity unpinned entries are queued, the oldest unpinned entry's release callback runs, freeing that object's data while the newer entries keep theirs. This bounds memory that would otherwise grow with every retained object over the life of the process — e.g. MTC introspection data parked in subtree blackboards until the Objective is unloaded. The queue never extends an owner's lifetime: owners are tracked through weak pointers, and entries whose owner has been destroyed are dropped without running their release callback. Re-retaining an owner that is already queued moves it to the newest slot (its pins carry over) instead of leaving a stale entry that would release its data early.
retain() returns a Pin that marks the entry in use: a pinned entry is never released, so callers hold the Pin for as long as they read or mutate the owner's retained data, and eviction skips it and evicts the next-oldest unpinned entry instead. Dropping the last Pin makes the entry evictable again (and triggers an eviction sweep, so with capacity zero the data is released as soon as its last Pin drops). The memory bound is therefore capacity + number of concurrently pinned entries.
Thread-safe. Release callbacks run under the queue's lock, which is what closes the gap between an eviction starting and a concurrent retain() of the same owner: once retain() returns, no release of that owner is queued or running. Because callbacks run under the lock they must not call back into this queue (they would deadlock), and a slow callback delays concurrent retains — pair each owner with a callback that only frees that owner's data, preferably through a domain wrapper (e.g. mtc_utils::retainTaskIntrospection) rather than ad-hoc lambdas at call sites, so the owner and the data being released cannot be mismatched.
Definition at line 42 of file bounded_retention_queue.hpp.
Public Constructors
BoundedRetentionQueue()
| explicit |
Creates a queue that keeps at most capacity unpinned entries retained.
A capacity of zero releases every entry as soon as its last Pin drops.
Declaration at line 72 of file bounded_retention_queue.hpp, definition at line 48 of file bounded_retention_queue.cpp.
Public Member Functions
capacity()
| noexcept |
The maximum number of unpinned entries kept retained.
Declaration at line 86 of file bounded_retention_queue.hpp, definition at line 52 of file bounded_retention_queue.cpp.
retain()
|
Retains owner's data and pins it in use; after the pin drops, the data is kept until capacity newer owners have been retained, then release is called.
Evicted entries' release callbacks run inside retain() (or inside the Pin destructor that made them evictable), under the queue's lock, on the calling thread, and only while their owner is still alive; a callback is never invoked twice for one entry. Callbacks must not call retain() reentrantly (see the class docstring). Discarding the returned Pin (e.g. via std::ignore) unpins immediately, retaining the data without marking it in use.
Declaration at line 83 of file bounded_retention_queue.hpp, definition at line 106 of file bounded_retention_queue.cpp.
Private Member Functions
sweepWhileLocked()
|
Releases oldest unpinned entries until at most capacity_ remain. Requires mutex_ to be held.
Declaration at line 97 of file bounded_retention_queue.hpp, definition at line 57 of file bounded_retention_queue.cpp.
unpin()
|
Drops one pin and sweeps, releasing entries the drop made evictable.
Declaration at line 100 of file bounded_retention_queue.hpp, definition at line 99 of file bounded_retention_queue.cpp.
Private Member Attributes
capacity_
|
Definition at line 102 of file bounded_retention_queue.hpp.
entries_
|
Definition at line 104 of file bounded_retention_queue.hpp.
mutex_
|
Definition at line 103 of file bounded_retention_queue.hpp.
The documentation for this class was generated from the following files:
Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.9.8.