Thread-safe recycling pool for instances of T with RAII acquisition. More...

#include <object_pool.h>

Inheritance diagram for vlink::ObjectPool< T >:

Collaboration diagram for vlink::ObjectPool< T >:

Classes
struct	PoolDeleter
	Custom deleter installed on every RAII handle handed out by `get` / `get_shared`. More...

Public Types
using	FactoryCallback = MoveFunction< std::unique_ptr< T >()>
	Signature of the factory used to grow the pool on demand. More...

using	ResetCallback = MoveFunction< void(T &)>
	Signature of the reset hook used to scrub objects on acquire and/or release. More...

Public Types inherited from vlink::ObjectPoolBase
enum	Policy : uint8_t { kPolicyNone = 0 , kPolicyRelease = 1 , kPolicyAcquire = 2 , kPolicyBoth = 3 }
	Decides when (or whether) the user-supplied `ResetCallback` runs. More...

Public Member Functions
	ObjectPool (FactoryCallback factory_callback=get_default_factory(), size_t initial_size=0, size_t max_size=0, ResetCallback reset_callback=nullptr, Policy policy=kPolicyRelease)
	Constructs the pool and optionally pre-warms the free list. More...

std::unique_ptr< T, typename ObjectPool< T >::PoolDeleter >	get ()
	Acquires an object wrapped in a `unique_ptr` with automatic return. More...

std::shared_ptr< T >	get_shared ()
	Acquires an object wrapped in a `shared_ptr` with automatic return. More...

T *	borrow ()
	Acquires an object as a raw pointer; the caller owns the return path. More...

void	give_back (T *ptr)
	Returns an object obtained from `borrow()` back to the pool. More...

Stats	stats () const
	Captures a thread-safe snapshot of pool statistics. More...

size_t	size () const
	Returns the number of objects currently idle on the free list. More...

Public Member Functions inherited from vlink::ObjectPoolBase
size_t	borrowed () const
	Returns the number of objects currently checked out of the pool. More...

size_t	total_created () const
	Returns the cumulative number of objects ever produced by the factory. More...

size_t	max_size () const noexcept
	Returns the configured upper bound on live objects. More...

Additional Inherited Members
Protected Member Functions inherited from vlink::ObjectPoolBase
	ObjectPoolBase (size_t max_size, size_t initial_size, Policy policy)

	~ObjectPoolBase () noexcept=default

void	safe_dec_borrowed_and_live () noexcept

bool	should_reset_on_acquire () const noexcept

bool	should_reset_on_release () const noexcept

void	throw_exhausted (size_t pool_size) const

Static Protected Member Functions inherited from vlink::ObjectPoolBase
static void	throw_invalid_size ()

static void	throw_factory_null_pre_fill ()

static void	throw_factory_null ()

Protected Attributes inherited from vlink::ObjectPoolBase
Policy	policy_ {kPolicyNone}

size_t	max_size_ {0}

std::mutex	mutex_

size_t	borrowed_ {0}

size_t	live_count_ {0}

size_t	total_created_ {0}

Detailed Description

template<typename T>
class vlink::ObjectPool< T >

Thread-safe recycling pool for instances of T with RAII acquisition.

Must always live behind a std::shared_ptr because PoolDeleter holds a std::weak_ptr back to the owning pool; constructing one on the stack leaks outstanding RAII handles into a dangling pool. Use std::make_shared<ObjectPool<T>>().

Template Parameters

T	Pooled element type. Must be default-constructible unless a non-default factory callback is supplied.

Member Typedef Documentation

◆ FactoryCallback

template<typename T >

using vlink::ObjectPool< T >::FactoryCallback = MoveFunction<std::unique_ptr<T>()>

Signature of the factory used to grow the pool on demand.

A non-null std::unique_ptr<T> must be returned; nullptr or thrown exceptions are propagated to the caller of get / get_shared / borrow.

◆ ResetCallback

template<typename T >

using vlink::ObjectPool< T >::ResetCallback = MoveFunction<void(T&)>

Signature of the reset hook used to scrub objects on acquire and/or release.

Exceptions thrown on the release path are swallowed and the affected object is discarded. Exceptions on the acquire path return the object to the pool and rethrow to the caller.

Constructor & Destructor Documentation

◆ ObjectPool()

template<typename T >

vlink::ObjectPool< T >::ObjectPool	(	FactoryCallback	factory_callback = `get_default_factory()`,
		size_t	initial_size = `0`,
		size_t	max_size = `0`,
		ResetCallback	reset_callback = `nullptr`,
		Policy	policy = `kPolicyRelease`
	)

inlineexplicit

Constructs the pool and optionally pre-warms the free list.

Details.

Parameters

factory_callback	Factory used to grow the pool. Default: `std::make_unique<T>()`.
initial_size	Objects to allocate eagerly at construction time.
max_size	Cap on the number of live objects. `0` means unlimited.
reset_callback	Optional scrubbing hook driven by `policy`.
policy	When the reset hook fires. Default: `kPolicyRelease`.

Exceptions

std::invalid_argument	when `initial_size` exceeds a non-zero `max_size`.
std::runtime_error	when the factory returns `nullptr` while pre-filling.

Note: Always construct via std::make_shared<ObjectPool<T>>() so that PoolDeleter can resolve its weak_ptr.

Here is the call graph for this function:

Member Function Documentation

◆ borrow()

template<typename T >

T * vlink::ObjectPool< T >::borrow

inline

Acquires an object as a raw pointer; the caller owns the return path.

Returns: Raw pointer that must later be returned via give_back().

Exceptions

std::runtime_error when the pool is exhausted or the factory fails.

◆ get()

template<typename T >

std::unique_ptr< T, typename ObjectPool< T >::PoolDeleter > vlink::ObjectPool< T >::get

inline

Acquires an object wrapped in a unique_ptr with automatic return.

Returns: RAII handle whose deleter releases the object back to the pool.

Exceptions

std::runtime_error when the pool is exhausted or the factory fails.

◆ get_shared()

template<typename T >

std::shared_ptr< T > vlink::ObjectPool< T >::get_shared

inline

Acquires an object wrapped in a shared_ptr with automatic return.

Returns: RAII handle whose deleter releases the object back to the pool.

Exceptions

std::runtime_error when the pool is exhausted or the factory fails.

◆ give_back()

template<typename T >

void vlink::ObjectPool< T >::give_back ( T * ptr )

inline

Returns an object obtained from borrow() back to the pool.

Parameters

ptr	Raw pointer previously returned by `borrow()`; `nullptr` is ignored.

◆ size()

template<typename T >

size_t vlink::ObjectPool< T >::size

inline

Returns the number of objects currently idle on the free list.

Returns: Idle object count.

◆ stats()

template<typename T >

ObjectPoolBase::Stats vlink::ObjectPool< T >::stats

inline

Captures a thread-safe snapshot of pool statistics.

Returns: Filled Stats value.

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

include/vlink/base/object_pool.h

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

template<typename T> class vlink::ObjectPool< T >

Member Typedef Documentation

◆ FactoryCallback

◆ ResetCallback

Constructor & Destructor Documentation

◆ ObjectPool()

Member Function Documentation

◆ borrow()

◆ get()

◆ get_shared()

◆ give_back()

◆ size()

◆ stats()

template<typename T>
class vlink::ObjectPool< T >