Bounds how many recently-retained objects keep their heavyweight data alive. More...

#include <bounded_retention_queue.hpp>

Classes
class	Pin
	RAII in-use marker for a retained entry; the entry cannot be released while any of its Pins is alive. More...

Public Member Functions
	BoundedRetentionQueue (std::size_t capacity)
	Creates a queue that keeps at most `capacity` unpinned entries retained.

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.

std::size_t	capacity () const noexcept
	The maximum number of unpinned entries kept retained.

Detailed 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.

Constructor & Destructor Documentation

◆ BoundedRetentionQueue()

moveit_pro::behaviors::BoundedRetentionQueue::BoundedRetentionQueue ( std::size_t capacity )

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.

Member Function Documentation

◆ capacity()

std::size_t moveit_pro::behaviors::BoundedRetentionQueue::capacity ( ) const

noexcept

The maximum number of unpinned entries kept retained.

◆ retain()

BoundedRetentionQueue::Pin moveit_pro::behaviors::BoundedRetentionQueue::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.

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.

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