vlink::ObjectPool< T > 模板类 参考

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

#include <object_pool.h>

类 vlink::ObjectPool< T > 继承关系图:

vlink::ObjectPool< T > 的协作图:

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

Public 类型
enum	Policy : uint8_t { kPolicyNone = 0 , kPolicyRelease = 1 , kPolicyAcquire = 2 , kPolicyBoth = 3 }
	Controls when the ResetCallback is invoked relative to acquire and release. 更多...
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 成员函数
	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.

详细描述

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>>(...).

模板参数

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

成员类型定义说明

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.

成员枚举类型说明

Policy

template<typename T>

enum vlink::ObjectPool::Policy : uint8_t

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

枚举值
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.

构造及析构函数说明

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

参数

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

异常

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

注解

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

函数调用图:

成员函数说明

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.

返回

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

异常

std::runtime_error

if the pool is exhausted or the factory returns nullptr.

警告

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.

返回

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.

返回

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

异常

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.

返回

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

异常

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.

参数

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

注解

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.

返回

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

这是这个函数的调用关系图:

size()

template<typename T>

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

inlinenodiscard

Returns the number of idle objects currently in the pool.

返回

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

返回

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.

返回

Cumulative creation count.

---

该类的文档由以下文件生成:

• include/vlink/base/object_pool.h