vlink::ObjectPool< T > Class Template Reference

Thread-safe object pool for type T with RAII acquisition and configurable reset policy. More...

#include <object_pool.h>

Inheritance diagram for vlink::ObjectPool< T >:

Collaboration diagram for vlink::ObjectPool< T >:

Classes
struct	Stats
	Snapshot of pool statistics at a point in time. More...
struct	PoolDeleter
	Custom deleter for RAII handles returned by get() and get_shared(). More...

Public Types
enum	Policy : uint8_t { kPolicyNone = 0 , kPolicyRelease = 1 , kPolicyAcquire = 2 , kPolicyBoth = 3 }
	Controls when the ResetCallback is invoked relative to acquire and release. More...
using	FactoryCallback = std::function<std::unique_ptr<T>()>
	Callback type for creating a new instance of T.
using	ResetCallback = std::function<void(T&)>
	Callback type for resetting an object before acquisition or after release.

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-populates it with objects.
std::unique_ptr< T, typename ObjectPool< T >::PoolDeleter >	get ()
	Acquires an object and returns it as a unique_ptr with automatic pool return.
std::shared_ptr< T >	get_shared ()
	Acquires an object and returns it as a shared_ptr with automatic pool return.
T *	borrow ()
	Acquires an object and returns a raw pointer; caller is responsible for returning it.
void	give_back (T *ptr)
	Returns a raw-pointer object previously obtained via borrow() to the pool.
Stats	stats () const
	Returns a snapshot of all pool statistics (thread-safe).
size_t	size () const
	Returns the number of idle objects currently in the pool.
size_t	borrowed () const
	Returns the number of objects currently held by callers.
size_t	total_created () const
	Returns the total number of objects ever created by this pool.
size_t	max_size () const
	Returns the maximum total object count allowed by this pool.

Detailed Description

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

Thread-safe object pool for type T with RAII acquisition and configurable reset policy.

Must be heap-allocated and managed via std::shared_ptr, because PoolDeleter holds a std::weak_ptr to the pool. Create with std::make_shared<ObjectPool<T>>(...).

Template Parameters

T	Type of pooled objects. Must be default-constructible unless a custom FactoryCallback is supplied.

Member Typedef Documentation

FactoryCallback

template<typename T>

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

Callback type for creating a new instance of T.

Must return a non-null unique_ptr<T>. Throwing or returning nullptr causes the acquisition call to propagate the error to the caller.

ResetCallback

template<typename T>

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

Callback type for resetting an object before acquisition or after release.

Called with a reference to the object. Exceptions thrown here are caught; on release, the object is discarded (not returned to the pool) if the reset throws.

Member Enumeration Documentation

Policy

template<typename T>

enum vlink::ObjectPool::Policy : uint8_t

Controls when the ResetCallback is invoked relative to acquire and release.

Enumerator
kPolicyNone	Never invoke reset callback.
kPolicyRelease	Invoke reset callback when object is returned to the pool.
kPolicyAcquire	Invoke reset callback when object is acquired from the pool.
kPolicyBoth	Invoke reset callback on both acquire and release.

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-populates it with objects.

Details.

Parameters

factory_callback	Factory used to create new T instances. Default: std::make_unique<T>().
initial_size	Number of objects to pre-allocate at construction. The reset callback (if kPolicyRelease or kPolicyBoth) is invoked on each pre-allocated object.
max_size	Upper bound on total objects (idle + borrowed). 0 = unlimited.
reset_callback	Optional callback invoked to reset objects per policy.
policy	When to invoke reset_callback (default kPolicyRelease).

Exceptions

std::invalid_argument	if initial_size > max_size and max_size > 0.
std::runtime_error	if factory_callback returns nullptr during pre-fill.

Note

Must be used via std::make_shared<ObjectPool<T>>(...) to enable PoolDeleter.

Here is the call graph for this function:

Member Function Documentation

borrow()

template<typename T>

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

inlinenodiscard

Acquires an object and returns a raw pointer; caller is responsible for returning it.

Unlike get() and get_shared(), this method does NOT use RAII. The caller MUST call give_back() to return the object. Failure to do so causes a resource leak and may prevent the pool from reaching max_size when needed.

Returns

Raw pointer to the acquired object. Never nullptr on success.

Exceptions

std::runtime_error

if the pool is exhausted or the factory returns nullptr.

Warning

Pair every borrow() with a corresponding give_back() call.

borrowed()

template<typename T>

size_t vlink::ObjectPool< T >::borrowed ( ) const

inlinenodiscard

Returns the number of objects currently held by callers.

Returns

Count of objects acquired and not yet returned.

get()

template<typename T>

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

inlinenodiscard

Acquires an object and returns it as a unique_ptr with automatic pool return.

If the pool is non-empty, the most recently returned object is popped (LIFO). Otherwise a new object is created via the factory callback. If kPolicyAcquire or kPolicyBoth is set, the reset callback is applied before returning the pointer.

Returns

A unique_ptr<T, PoolDeleter> whose destruction returns the object to the pool.

Exceptions

std::runtime_error

if the pool is exhausted (max_size > 0 and all objects are in use), or if the factory callback returns nullptr.

get_shared()

template<typename T>

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

inlinenodiscard

Acquires an object and returns it as a shared_ptr with automatic pool return.

Behaves identically to get() but returns a shared_ptr. The custom deleter is PoolDeleter, so the object is returned to the pool when the last shared_ptr copy is destroyed.

Returns

A shared_ptr<T> that returns the object to the pool on last-reference destruction.

Exceptions

std::runtime_error

if the pool is exhausted or the factory returns nullptr.

give_back()

template<typename T>

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

inline

Returns a raw-pointer object previously obtained via borrow() to the pool.

If the reset policy includes kPolicyRelease, the reset callback is invoked before the object re-enters the pool. If the reset callback throws, the object is discarded rather than returned.

Parameters

ptr	Pointer returned by borrow(). Passing nullptr is a no-op.

Note

Do NOT call give_back() on pointers obtained from get() or get_shared(); those are managed by their respective deleters.

max_size()

template<typename T>

size_t vlink::ObjectPool< T >::max_size ( ) const

inlinenodiscard

Returns the maximum total object count allowed by this pool.

Returns

Max size limit. Returns 0 if the pool is unbounded.

Here is the caller graph for this function:

size()

template<typename T>

size_t vlink::ObjectPool< T >::size ( ) const

inlinenodiscard

Returns the number of idle objects currently in the pool.

Returns

Number of available objects that can be acquired without allocation.

stats()

template<typename T>

ObjectPool< T >::Stats vlink::ObjectPool< T >::stats ( ) const

inlinenodiscard

Returns a snapshot of all pool statistics (thread-safe).

Returns

Stats struct containing pool_size, borrowed, total_created, max_size.

total_created()

template<typename T>

size_t vlink::ObjectPool< T >::total_created ( ) const

inlinenodiscard

Returns the total number of objects ever created by this pool.

Includes objects currently idle, borrowed, and any that were discarded due to failed reset callbacks. Never decreases.

Returns

Cumulative creation count.

---

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

• include/vlink/base/object_pool.h