Thread-local cached object pool for improved multi-threaded performance. More...

#include <object_pool.h>

Collaboration diagram for kcenon::logger::memory::thread_local_object_pool< T >:

Classes
struct	config
	Configuration for thread-local object pool. More...

struct	statistics
	Statistics for monitoring pool performance. More...

Public Member Functions
	thread_local_object_pool (const config &cfg=config{})
	Construct thread-local object pool with configuration.

	~thread_local_object_pool ()=default
	Destructor.

std::unique_ptr< T >	acquire ()
	Get an object from the pool.

void	release (std::unique_ptr< T > obj)
	Return an object to the pool.

statistics	get_statistics () const
	Get pool statistics.

void	clear ()
	Clear all objects from pool.

Private Member Functions
void	initialize_pool ()
	Initialize pool with initial objects.

Static Private Member Functions
static std::vector< std::unique_ptr< T > > &	get_local_cache ()
	Get thread-local cache.

Private Attributes
config	config_

std::vector< std::unique_ptr< T > >	global_pool_

std::mutex	global_mutex_

std::atomic< size_t >	global_size_ {0}

std::atomic< size_t >	local_cache_hits_ {0}

std::atomic< size_t >	global_pool_hits_ {0}

std::atomic< size_t >	new_allocations_ {0}

Detailed Description

template<typename T>
class kcenon::logger::memory::thread_local_object_pool< T >

Thread-local cached object pool for improved multi-threaded performance.

Template Parameters

T	The type of objects to pool

This implementation uses thread-local caching to minimize lock contention in multi-threaded environments. Each thread maintains a small local cache of objects, only accessing the global pool when the local cache is empty or full.

Performance characteristics:

Single thread: Similar to object_pool
Multi-threaded: 2-5x better than object_pool due to reduced lock contention

Memory overhead:

Each thread uses up to local_cache_size * sizeof(T*) additional memory
Recommended local_cache_size: 16 (empirically optimal)

Since: 1.1.0

Definition at line 169 of file object_pool.h.

Constructor & Destructor Documentation

◆ thread_local_object_pool()

template<typename T >

kcenon::logger::memory::thread_local_object_pool< T >::thread_local_object_pool ( const config & cfg = config{} )

inlineexplicit

Construct thread-local object pool with configuration.

Parameters

cfg	Pool configuration

Definition at line 187 of file object_pool.h.

                                                                {})
        : config_(cfg)
        , global_size_(0) {
        initialize_pool();
    }

◆ ~thread_local_object_pool()

template<typename T >

kcenon::logger::memory::thread_local_object_pool< T >::~thread_local_object_pool ( )

default

Destructor.

Member Function Documentation

◆ acquire()

template<typename T >

std::unique_ptr< T > kcenon::logger::memory::thread_local_object_pool< T >::acquire ( )

inline

Get an object from the pool.

Returns: Unique pointer to object

Attempts to acquire from thread-local cache first (no lock), then from global pool in batches (single lock), and creates new if needed.

Definition at line 205 of file object_pool.h.

                               {
        // Step 1: Check thread-local cache first (no lock!)
        auto& local_cache = get_local_cache();
 
        if (!local_cache.empty()) {
            local_cache_hits_.fetch_add(1, std::memory_order_relaxed);
            auto obj = std::move(local_cache.back());
            local_cache.pop_back();
            return obj;
        }
 
        // Step 2: Fetch batch from global pool (lock once)
        {
            std::lock_guard<std::mutex> lock(global_mutex_);
 
            // Batch size: half of local cache size
            size_t batch_size = std::min(
                config_.local_cache_size / 2,
                global_pool_.size()
            );
 
            for (size_t i = 0; i < batch_size; ++i) {
                if (!global_pool_.empty()) {
                    local_cache.push_back(std::move(global_pool_.back()));
                    global_pool_.pop_back();
                }
            }
        }
 
        // Step 3: Try local cache again after batch fetch
        if (!local_cache.empty()) {
            global_pool_hits_.fetch_add(1, std::memory_order_relaxed);
            auto obj = std::move(local_cache.back());
            local_cache.pop_back();
            return obj;
        }
 
        // Step 4: Create new object if pool is empty
        if (config_.allow_growth && global_size_.load(std::memory_order_relaxed) < config_.global_max) {
            global_size_.fetch_add(1, std::memory_order_relaxed);
            new_allocations_.fetch_add(1, std::memory_order_relaxed);
            return std::make_unique<T>();
        }
 
        // Fallback: create temporary object even if limit reached
        // (same behavior as original object_pool)
        return std::make_unique<T>();
    }

Here is the call graph for this function:

◆ clear()

template<typename T >

void kcenon::logger::memory::thread_local_object_pool< T >::clear ( )

inline

Clear all objects from pool.

Warning: This does not clear thread-local caches

Definition at line 326 of file object_pool.h.

                 {
        std::lock_guard<std::mutex> lock(global_mutex_);
        global_pool_.clear();
        global_size_.store(0, std::memory_order_relaxed);
        local_cache_hits_.store(0, std::memory_order_relaxed);
        global_pool_hits_.store(0, std::memory_order_relaxed);
        new_allocations_.store(0, std::memory_order_relaxed);
    }

References kcenon::logger::memory::thread_local_object_pool< T >::global_mutex_, kcenon::logger::memory::thread_local_object_pool< T >::global_pool_, kcenon::logger::memory::thread_local_object_pool< T >::global_pool_hits_, kcenon::logger::memory::thread_local_object_pool< T >::global_size_, kcenon::logger::memory::thread_local_object_pool< T >::local_cache_hits_, and kcenon::logger::memory::thread_local_object_pool< T >::new_allocations_.

◆ get_local_cache()

template<typename T >

static std::vector< std::unique_ptr< T > > & kcenon::logger::memory::thread_local_object_pool< T >::get_local_cache ( )

inlinestaticprivate

Get thread-local cache.

Returns: Reference to thread-local cache vector

Definition at line 340 of file object_pool.h.

                                                          {
        thread_local std::vector<std::unique_ptr<T>> cache;
        return cache;
    }

Referenced by kcenon::logger::memory::thread_local_object_pool< T >::acquire(), and kcenon::logger::memory::thread_local_object_pool< T >::release().

Here is the caller graph for this function:

◆ get_statistics()

template<typename T >

statistics kcenon::logger::memory::thread_local_object_pool< T >::get_statistics ( ) const

inline

Get pool statistics.

Returns: Current pool statistics

Definition at line 311 of file object_pool.h.

                                      {
        std::lock_guard<std::mutex> lock(global_mutex_);
        statistics stats;
        stats.global_size = global_size_.load(std::memory_order_relaxed);
        stats.global_pool_size = global_pool_.size();
        stats.local_cache_hits = local_cache_hits_.load(std::memory_order_relaxed);
        stats.global_pool_hits = global_pool_hits_.load(std::memory_order_relaxed);
        stats.new_allocations = new_allocations_.load(std::memory_order_relaxed);
        return stats;
    }

◆ initialize_pool()

template<typename T >

void kcenon::logger::memory::thread_local_object_pool< T >::initialize_pool ( )

inlineprivate

Initialize pool with initial objects.

Definition at line 348 of file object_pool.h.

                           {
        std::lock_guard<std::mutex> lock(global_mutex_);
 
        for (size_t i = 0; i < config_.initial_size; ++i) {
            global_pool_.push_back(std::make_unique<T>());
        }
 
        global_size_.store(config_.initial_size, std::memory_order_relaxed);
    }

References kcenon::logger::memory::thread_local_object_pool< T >::config_, kcenon::logger::memory::thread_local_object_pool< T >::global_mutex_, kcenon::logger::memory::thread_local_object_pool< T >::global_pool_, kcenon::logger::memory::thread_local_object_pool< T >::global_size_, and kcenon::logger::memory::thread_local_object_pool< T >::config::initial_size.

◆ release()

template<typename T >

void kcenon::logger::memory::thread_local_object_pool< T >::release ( std::unique_ptr< T > obj )

inline

Return an object to the pool.

Parameters

obj	Object to return

Adds to thread-local cache if space available (no lock), otherwise transfers batch to global pool (single lock).

Definition at line 261 of file object_pool.h.

                                       {
        if (!obj) {
            return;
        }
 
        // Step 1: Add to thread-local cache (no lock!)
        auto& local_cache = get_local_cache();
 
        if (local_cache.size() < config_.local_cache_size) {
            local_cache.push_back(std::move(obj));
            return;
        }
 
        // Step 2: Transfer batch to global pool when local cache is full
        {
            std::lock_guard<std::mutex> lock(global_mutex_);
 
            // Move half of local cache to global
            size_t transfer_count = config_.local_cache_size / 2;
 
            for (size_t i = 0; i < transfer_count && !local_cache.empty(); ++i) {
                if (global_pool_.size() < config_.global_max) {
                    global_pool_.push_back(std::move(local_cache.back()));
                    local_cache.pop_back();
                }
            }
 
            // Add current object to global pool
            if (global_pool_.size() < config_.global_max) {
                global_pool_.push_back(std::move(obj));
            }
            // If exceeding max, object will be destroyed automatically
        }
    }