nfx::string::StringBuilderPool Class Reference

Thread-safe memory pool for high-performance StringBuilder instances with optimized allocation strategy. More...

#include <nfx/string/StringBuilderPool.h>

Classes
struct	PoolStatistics
	Pool performance statistics for external access. More...

Static Public Member Functions
static StringBuilderLease	lease ()
	Creates a new StringBuilder lease with an optimally sourced memory buffer.
static PoolStatistics	stats () noexcept
	Gets current pool statistics.
static void	resetStats () noexcept
	Resets pool statistics.
static size_t	clear ()
	Clears all buffers from the pool and returns the count of cleared buffers.
static size_t	size () noexcept
	Gets current number of buffers stored in the pool.

Detailed Description

Thread-safe memory pool for high-performance StringBuilder instances with optimized allocation strategy.

Implements a three-tier pooling system for DynamicStringBuffer instances to minimize allocation overhead in high-frequency string building scenarios. Features thread-local caching, shared cross-thread pooling, and comprehensive statistics tracking. Designed as a singleton with static factory methods for global access.

Three-Tier Pooling Architecture:

StringBuilderPool::lease() Buffer Acquisition Strategy:
┌─────────────────────────────────────────────────────────────┐
│                      Client Request                         │
│               StringBuilderPool::lease()                    │
└─────────────────────────────────────────────────────────────┘
                             ↓ (try first)
┌─────────────────────────────────────────────────────────────┐
│               Tier 1: Thread-Local Cache                    │ ← Fastest (no locks)
│  ┌─────────────────────────────────────────────────────┐    │
│  │     thread_local DynamicStringBuffer* cache         │    │
│  │       - Zero synchronization overhead               │    │
│  │       - Immediate buffer availability               │    │
│  │       - Perfect for single-threaded hotpaths        │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                             ↓ (on miss - cache empty)
┌─────────────────────────────────────────────────────────────┐
│            Tier 2: Shared Cross-Thread Pool                 │ ← Fast (mutex-protected)
│  ┌─────────────────────────────────────────────────────┐    │
│  │   DynamicStringBufferPool (singleton)               │    │
│  │       - Mutex-protected buffer queue                │    │
│  │       - Cross-thread buffer sharing                 │    │
│  │       - Size-limited to prevent bloat               │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                             ↓ (on miss - pool empty)
┌─────────────────────────────────────────────────────────────┐
│                Tier 3: New Allocation                       │ ← Fallback (heap allocation)
│  ┌─────────────────────────────────────────────────────┐    │
│  │   new DynamicStringBuffer(optimal_size)             │    │
│  │       - Pre-sized for typical usage patterns        │    │
│  │       - Small Buffer Optimization (256-byte stack)  │    │
│  │       - 1.5x growth factor for cache efficiency     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
 
Buffer Return Process (via StringBuilderLease destructor):
┌─────────────────────────────────────────────────────────────┐
│  1. Clear buffer content (zero-cost operation)              │
│  2. Check size limits (prevent memory bloat)                │
│  3. Return to thread-local cache (if space available)       │
│  4. Return to shared pool (if thread-local full)            │
│  5. Deallocate (if both pools full or buffer too large)     │
└─────────────────────────────────────────────────────────────┘

Note

This class uses a singleton pattern with static methods - no instantiation required. All pool operations are thread-safe and optimized for concurrent access patterns.

Warning

Pool buffers have size limits to prevent memory bloat - extremely large buffers may not be returned to the pool and will be deallocated normally.

See also

StringBuilderLease for RAII buffer management

StringBuilder for the high-level string building interface

DynamicStringBuffer for the underlying buffer implementation

Definition at line 857 of file StringBuilderPool.h.

Member Function Documentation

clear()

static size_t nfx::string::StringBuilderPool::clear ( )

static

Clears all buffers from the pool and returns the count of cleared buffers.

Returns

Number of buffers that were cleared from the pool

lease()

static StringBuilderLease nfx::string::StringBuilderPool::lease ( )

static

Creates a new StringBuilder lease with an optimally sourced memory buffer.

Returns

StringBuilderLease managing a pooled buffer with automatic cleanup

This is the primary factory method for obtaining StringBuilder instances. The buffer is sourced using a three-tier optimization strategy:

1. Thread-local cache (fastest, zero synchronization overhead)
2. Shared cross-thread pool (fast, mutex-protected access)
3. New allocation (fallback, pre-sized for optimal performance)

The returned lease automatically returns the buffer to the pool when destroyed, ensuring optimal memory reuse and preventing leaks.

This method is thread-safe and optimized for high-frequency usage patterns. Buffers are automatically cleared before reuse and size-limited to prevent bloat.

size()

static size_t nfx::string::StringBuilderPool::size ( )

staticnoexcept

Gets current number of buffers stored in the pool.

Returns

Number of buffers currently available in the pool

stats()

static PoolStatistics nfx::string::StringBuilderPool::stats ( )

staticnoexcept

Gets current pool statistics.

Returns

Current pool performance statistics structure

---

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

• StringBuilderPool.h