nfx::string::StringBuilderPool Class Reference

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

#include <nfx/string/StringBuilder.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 StringBuilderLease	lease (size_t capacityHint)
	Creates a new StringBuilder lease with pre-allocated capacity hint.
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 867 of file StringBuilder.h.

Member Function Documentation

clear()

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

Here is the call graph for this function:

Here is the caller graph for this function:

lease() [1/2]

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

staticnodiscard

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.

lease() [2/2]

StringBuilderLease nfx::string::StringBuilderPool::lease ( size_t capacityHint )

staticnodiscard

Creates a new StringBuilder lease with pre-allocated capacity hint.

Parameters

capacityHint

Minimum desired buffer capacity in bytes

Returns

StringBuilderLease managing a pooled buffer with automatic cleanup

Pre-allocates buffer capacity to avoid reallocations during string construction. The buffer is sourced using the same three-tier optimization strategy as lease(), but with an additional reserve() call to ensure sufficient capacity.

Use this overload when the approximate final size is known in advance to minimize memory allocations and improve performance.

Example:

// Building a SQL query (~500 bytes expected)
auto lease = StringBuilderPool::lease(512);
auto builder = lease.create();
builder << "SELECT * FROM users WHERE ...";

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

Note

The hint is a minimum - the actual capacity may be larger due to pooling or growth factor optimizations. Existing pooled buffers retain their capacity.

size()

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

Here is the call graph for this function:

Here is the caller graph for this function:

stats()

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:

• StringBuilder.h