Thread-safe object pool that reuses raw storage for expensive objects. More...

#include <object_pool.h>

Collaboration diagram for kcenon::common::utils::ObjectPool< T >:

Public Types
using	value_type = T

using	deleter_type = PoolDeleter<T>

using	pointer_type = std::unique_ptr<T, deleter_type>

Public Member Functions
	ObjectPool (std::size_t growth=32)
	Construct an object pool with the specified growth factor.

template<typename... Args>
pointer_type	acquire (bool *reused, Args &&... args)
	Acquire an object constructed with the provided arguments.

template<typename... Args>
pointer_type	acquire (Args &&... args)

void	release (T *ptr) noexcept
	Return raw storage to the pool (destructor already run).

void	reserve (std::size_t count)
	Add `count` additional blocks to the pool.

void	clear ()
	Destroy all cached instances and release memory.

std::size_t	available () const

	ObjectPool (std::size_t growth=32)

template<typename... Args>
std::unique_ptr< T, std::function< void(T *)> >	acquire (bool *reused, Args &&... args)
	Acquire an object constructed with the provided arguments.

template<typename... Args>
std::unique_ptr< T, std::function< void(T *)> >	acquire (Args &&... args)

void	release (T *ptr) noexcept
	Return raw storage to the pool (destructor already run).

void	reserve (std::size_t count)
	Add count additional blocks to the pool.

void	clear ()
	Destroy all cached instances and release memory.

std::size_t	available () const

Private Types
using	RawPtr = std::unique_ptr<T, detail::RawDelete<T>>

Private Member Functions
void	allocate_block_unlocked (std::size_t count)

void	allocate_block_unlocked (std::size_t count)

Private Attributes
std::size_t	growth_

std::mutex	mutex_

std::stack< T * >	free_list_

std::vector< RawPtr >	storage_

Detailed Description

template<typename T>
class kcenon::common::utils::ObjectPool< T >

Thread-safe object pool that reuses raw storage for expensive objects.

The pool allocates raw memory once and performs placement-new construction on acquisition. Objects are destructed when released, but the underlying storage is retained for fast reuse.

Template Parameters

T	Object type to pool

Examples: utility_containers_example.cpp.

Definition at line 218 of file utils.cppm.

Member Typedef Documentation

◆ deleter_type

template<typename T >

using kcenon::common::utils::ObjectPool< T >::deleter_type = PoolDeleter<T>

Definition at line 65 of file object_pool.h.

◆ pointer_type

template<typename T >

using kcenon::common::utils::ObjectPool< T >::pointer_type = std::unique_ptr<T, deleter_type>

Definition at line 66 of file object_pool.h.

◆ RawPtr

template<typename T >

using kcenon::common::utils::ObjectPool< T >::RawPtr = std::unique_ptr<T, detail::RawDelete<T>>

exportprivate

Definition at line 149 of file object_pool.h.

◆ value_type

template<typename T >

typedef T kcenon::common::utils::ObjectPool< T >::value_type = T

export

Definition at line 64 of file object_pool.h.

Constructor & Destructor Documentation

◆ ObjectPool() [1/2]

template<typename T >

kcenon::common::utils::ObjectPool< T >::ObjectPool ( std::size_t growth = 32 )

inlineexplicit

Construct an object pool with the specified growth factor.

Parameters

growth Number of objects to pre-allocate per expansion (minimum 1).

Definition at line 72 of file object_pool.h.

73 : growth_(growth == 0 ? 1 : growth) {}

kcenon::common::utils::ObjectPool::growth_

std::size_t growth_

Definition object_pool.h:159

◆ ObjectPool() [2/2]

template<typename T >

kcenon::common::utils::ObjectPool< T >::ObjectPool ( std::size_t growth = 32 )

inlineexplicitexport

Definition at line 222 of file utils.cppm.

223 : growth_(growth == 0 ? 1 : growth) {}

Member Function Documentation

◆ acquire() [1/4]

template<typename T >

template<typename... Args>

pointer_type kcenon::common::utils::ObjectPool< T >::acquire ( Args &&... args )

inline

Definition at line 106 of file object_pool.h.

                                         {
        return acquire(static_cast<bool*>(nullptr), std::forward<Args>(args)...);
    }

References kcenon::common::utils::ObjectPool< T >::acquire().

Here is the call graph for this function:

◆ acquire() [2/4]

template<typename T >

template<typename... Args>

std::unique_ptr< T, std::function< void(T *)> > kcenon::common::utils::ObjectPool< T >::acquire ( Args &&... args )

inlineexport

Definition at line 258 of file utils.cppm.

                                                                    {
        return acquire(static_cast<bool*>(nullptr), std::forward<Args>(args)...);
    }

References kcenon::common::utils::ObjectPool< T >::acquire().

Here is the call graph for this function:

◆ acquire() [3/4]

template<typename T >

template<typename... Args>

pointer_type kcenon::common::utils::ObjectPool< T >::acquire	(	bool *	reused,
		Args &&...	args )

inline

Acquire an object constructed with the provided arguments.

Parameters

reused	Optional pointer that receives whether an existing block was reused.
args	Arguments forwarded to the object's constructor.

Returns: A unique_ptr to the acquired object with a custom deleter that returns it to the pool.

Definition at line 82 of file object_pool.h.

                                                       {
        T* raw = nullptr;
        bool reused_local = false;
        {
            std::lock_guard<std::mutex> lock(mutex_);
            if (free_list_.empty()) {
                allocate_block_unlocked(growth_);
            } else {
                reused_local = true;
            }
 
            raw = free_list_.top();
            free_list_.pop();
        }
 
        if (reused) {
            *reused = reused_local;
        }
 
        new (raw) T(std::forward<Args>(args)...);
        return pointer_type(raw, deleter_type{this});
    }

References kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked(), kcenon::common::utils::ObjectPool< T >::free_list_, kcenon::common::utils::ObjectPool< T >::growth_, and kcenon::common::utils::ObjectPool< T >::mutex_.

Referenced by kcenon::common::utils::ObjectPool< T >::acquire(), and main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ acquire() [4/4]

template<typename T >

template<typename... Args>

std::unique_ptr< T, std::function< void(T *)> > kcenon::common::utils::ObjectPool< T >::acquire	(	bool *	reused,
		Args &&...	args )

inlineexport

Acquire an object constructed with the provided arguments.

Parameters

reused	Optional pointer that receives whether an existing block was reused.
args	Arguments forwarded to the object's constructor.

Returns: A unique_ptr to the acquired object with a custom deleter.

Definition at line 232 of file utils.cppm.

                                                                                  {
        T* raw = nullptr;
        bool reused_local = false;
        {
            std::lock_guard<std::mutex> lock(mutex_);
            if (free_list_.empty()) {
                allocate_block_unlocked(growth_);
            } else {
                reused_local = true;
            }
 
            raw = free_list_.top();
            free_list_.pop();
        }
 
        if (reused) {
            *reused = reused_local;
        }
 
        new (raw) T(std::forward<Args>(args)...);
        return std::unique_ptr<T, std::function<void(T*)>>(raw, [this](T* ptr) {
            this->release(ptr);
        });
    }

References kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked(), kcenon::common::utils::ObjectPool< T >::free_list_, kcenon::common::utils::ObjectPool< T >::growth_, kcenon::common::utils::ObjectPool< T >::mutex_, and kcenon::common::utils::ObjectPool< T >::release().

Here is the call graph for this function:

◆ allocate_block_unlocked() [1/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked ( std::size_t count )

inlineprivate

Definition at line 151 of file object_pool.h.

                                                  {
        for (std::size_t i = 0; i < count; ++i) {
            RawPtr block(static_cast<T*>(::operator new(sizeof(T))));
            free_list_.push(block.get());
            storage_.push_back(std::move(block));
        }
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, and kcenon::common::utils::ObjectPool< T >::storage_.

Referenced by kcenon::common::utils::ObjectPool< T >::acquire(), and kcenon::common::utils::ObjectPool< T >::reserve().

Here is the caller graph for this function:

◆ allocate_block_unlocked() [2/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked ( std::size_t count )

inlineexportprivate

Definition at line 303 of file utils.cppm.

                                                  {
        for (std::size_t i = 0; i < count; ++i) {
            RawPtr block(static_cast<T*>(::operator new(sizeof(T))));
            free_list_.push(block.get());
            storage_.push_back(std::move(block));
        }
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, and kcenon::common::utils::ObjectPool< T >::storage_.

◆ available() [1/2]

template<typename T >

std::size_t kcenon::common::utils::ObjectPool< T >::available ( ) const

inlinenodiscard

Definition at line 143 of file object_pool.h.

                                              {
        std::lock_guard<std::mutex> lock(mutex_);
        return free_list_.size();
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, and kcenon::common::utils::ObjectPool< T >::mutex_.

Referenced by main().

Here is the caller graph for this function:

◆ available() [2/2]

template<typename T >

std::size_t kcenon::common::utils::ObjectPool< T >::available ( ) const

inlinenodiscardexport

Definition at line 295 of file utils.cppm.

                                              {
        std::lock_guard<std::mutex> lock(mutex_);
        return free_list_.size();
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, and kcenon::common::utils::ObjectPool< T >::mutex_.

◆ clear() [1/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::clear ( )

inline

Destroy all cached instances and release memory.

Definition at line 137 of file object_pool.h.

                 {
        std::lock_guard<std::mutex> lock(mutex_);
        free_list_ = std::stack<T*>();
        storage_.clear();
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, kcenon::common::utils::ObjectPool< T >::mutex_, and kcenon::common::utils::ObjectPool< T >::storage_.

Referenced by main().

Here is the caller graph for this function:

◆ clear() [2/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::clear ( )

inlineexport

Destroy all cached instances and release memory.

Definition at line 289 of file utils.cppm.

                 {
        std::lock_guard<std::mutex> lock(mutex_);
        free_list_ = std::stack<T*>();
        storage_.clear();
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, kcenon::common::utils::ObjectPool< T >::mutex_, and kcenon::common::utils::ObjectPool< T >::storage_.

◆ release() [1/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::release ( T * ptr )

inlinenoexcept

Return raw storage to the pool (destructor already run).

Definition at line 113 of file object_pool.h.

                                  {
        if (!ptr) {
            return;
        }
 
        ptr->~T();
        std::lock_guard<std::mutex> lock(mutex_);
        free_list_.push(ptr);
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, and kcenon::common::utils::ObjectPool< T >::mutex_.

Referenced by kcenon::common::utils::ObjectPool< T >::acquire().

Here is the caller graph for this function:

◆ release() [2/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::release ( T * ptr )

inlineexportnoexcept

Return raw storage to the pool (destructor already run).

Definition at line 265 of file utils.cppm.

                                  {
        if (!ptr) {
            return;
        }
 
        ptr->~T();
        std::lock_guard<std::mutex> lock(mutex_);
        free_list_.push(ptr);
    }

References kcenon::common::utils::ObjectPool< T >::free_list_, and kcenon::common::utils::ObjectPool< T >::mutex_.

◆ reserve() [1/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::reserve ( std::size_t count )

inline

Add count additional blocks to the pool.

Definition at line 126 of file object_pool.h.

                                  {
        if (count == 0) {
            return;
        }
        std::lock_guard<std::mutex> lock(mutex_);
        allocate_block_unlocked(count);
    }

References kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked(), and kcenon::common::utils::ObjectPool< T >::mutex_.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reserve() [2/2]

template<typename T >

void kcenon::common::utils::ObjectPool< T >::reserve ( std::size_t count )

inlineexport

Add count additional blocks to the pool.

Definition at line 278 of file utils.cppm.

                                  {
        if (count == 0) {
            return;
        }
        std::lock_guard<std::mutex> lock(mutex_);
        allocate_block_unlocked(count);
    }

References kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked(), and kcenon::common::utils::ObjectPool< T >::mutex_.

Here is the call graph for this function:

Member Data Documentation

◆ free_list_

template<typename T >

std::stack< T * > kcenon::common::utils::ObjectPool< T >::free_list_

exportprivate

Definition at line 161 of file object_pool.h.

Referenced by kcenon::common::utils::ObjectPool< T >::acquire(), kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked(), kcenon::common::utils::ObjectPool< T >::available(), kcenon::common::utils::ObjectPool< T >::clear(), and kcenon::common::utils::ObjectPool< T >::release().

◆ growth_

template<typename T >

std::size_t kcenon::common::utils::ObjectPool< T >::growth_

exportprivate

Definition at line 159 of file object_pool.h.

Referenced by kcenon::common::utils::ObjectPool< T >::acquire().

◆ mutex_

template<typename T >

std::mutex kcenon::common::utils::ObjectPool< T >::mutex_

mutableexportprivate

Definition at line 160 of file object_pool.h.

Referenced by kcenon::common::utils::ObjectPool< T >::acquire(), kcenon::common::utils::ObjectPool< T >::available(), kcenon::common::utils::ObjectPool< T >::clear(), kcenon::common::utils::ObjectPool< T >::release(), and kcenon::common::utils::ObjectPool< T >::reserve().

◆ storage_

template<typename T >

std::vector< RawPtr > kcenon::common::utils::ObjectPool< T >::storage_

exportprivate

Definition at line 162 of file object_pool.h.

Referenced by kcenon::common::utils::ObjectPool< T >::allocate_block_unlocked(), and kcenon::common::utils::ObjectPool< T >::clear().

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

include/kcenon/common/utils/object_pool.h
src/modules/utils.cppm

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ deleter_type

◆ pointer_type

◆ RawPtr

◆ value_type

Constructor & Destructor Documentation

◆ ObjectPool() [1/2]

◆ ObjectPool() [2/2]

Member Function Documentation

◆ acquire() [1/4]

◆ acquire() [2/4]

◆ acquire() [3/4]

◆ acquire() [4/4]

◆ allocate_block_unlocked() [1/2]

◆ allocate_block_unlocked() [2/2]

◆ available() [1/2]

◆ available() [2/2]

◆ clear() [1/2]

◆ clear() [2/2]

◆ release() [1/2]

◆ release() [2/2]

◆ reserve() [1/2]

◆ reserve() [2/2]

Member Data Documentation

◆ free_list_

◆ growth_

◆ mutex_

◆ storage_