Buffer Pool

🗃️ Pre-allocated memory buffers for efficient allocation More...

Files
file	buffer_pool.c
	💾 Lock-free memory pool with atomic operations
file	buffer_pool.h
	🗃️ Lock-Free Unified Memory Buffer Pool with Lazy Allocation

Data Structures
struct	buffer_node
	Node header embedded before user data. More...
struct	buffer_pool
	Unified buffer pool with lock-free fast path. More...

Macros
#define	BUFFER_POOL_MAX_BYTES   (337 * 1024 * 1024)
	Maximum total bytes the pool can hold (337 MB)
#define	BUFFER_POOL_SHRINK_DELAY_NS   5000000000ULL
	Time before unused buffers are freed (5 seconds in nanoseconds)
#define	BUFFER_POOL_MIN_SIZE   64
	Minimum buffer size to pool (smaller allocations use malloc directly)
#define	BUFFER_POOL_MAX_SINGLE_SIZE   (4 * 1024 * 1024)
	Maximum single buffer size to pool (larger allocations use malloc directly)
#define	BUFFER_POOL_MAGIC   MAGIC_BUFFER_POOL_VALID
	Magic value to identify pooled buffers - Alias for backward compatibility.
#define	BUFFER_POOL_MAGIC_FALLBACK   MAGIC_BUFFER_POOL_FALLBACK
	Magic value for malloc fallback buffers (not in pool) - Alias for backward compatibility.
#define	POOL_ALLOC(size)   buffer_pool_alloc(NULL, (size))
#define	POOL_FREE(data, size)   buffer_pool_free(NULL, (data), (size))

Typedefs
typedef struct buffer_node	buffer_node_t
	Node header embedded before user data.
typedef struct buffer_pool	buffer_pool_t
	Unified buffer pool with lock-free fast path.

Functions
buffer_pool_t *	buffer_pool_create (size_t max_bytes, uint64_t shrink_delay_ns)
	Create a new buffer pool.
void	buffer_pool_destroy (buffer_pool_t *pool)
	Destroy a buffer pool and free all memory.
void *	buffer_pool_alloc (buffer_pool_t *pool, size_t size)
	Allocate a buffer from the pool (lock-free fast path)
void	buffer_pool_free (buffer_pool_t *pool, const void *data, size_t size)
	Free a buffer back to the pool (lock-free)
void	buffer_pool_shrink (buffer_pool_t *pool)
	Force shrink the pool (free old unused buffers)
void	buffer_pool_get_stats (buffer_pool_t *pool, size_t *current_bytes, size_t *used_bytes, size_t *free_bytes)
	Get pool statistics (atomic reads)
void	buffer_pool_log_stats (buffer_pool_t *pool, const char *name)
	Log pool statistics.
void	buffer_pool_init_global (void)
void	buffer_pool_cleanup_global (void)
buffer_pool_t *	buffer_pool_get_global (void)

Detailed Description

🗃️ Pre-allocated memory buffers for efficient allocation

A mostly lock-free memory pool using atomic operations for the fast path. Allocations and frees use CAS on a lock-free stack. Only shrinking needs a lock.

DESIGN:

• Lock-free stack for free list (LIFO allocation)
• Node header embedded before data pointer (no search on free)
• Atomic counters for all statistics
• Only shrinking requires a lock (infrequent)

MEMORY LIMITS:

Default max: 337 MB (supports 32 clients at 144fps)

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

December 2025

Buffer Pool

Overview

Welcome! Let's talk about the buffer pool system—one of the secret weapons for making ascii-chat's real-time video streaming fast and smooth.

You know how constantly calling malloc() and free() can slow things down? Well, imagine doing that 30 times per second for video frames, per client! The buffer pool solves this by pre-allocating a bunch of memory buffers up front, so when you need one, it's ready to go. No waiting for the system allocator, no frame drops, no latency spikes—just grab a buffer and get to work.

Think of it like having a stack of clean plates ready for a dinner party. Instead of washing a plate every time someone needs one, you just grab from the stack. Much faster!

Implementation: lib/buffer_pool.c/h

What does the buffer pool give you?

• Multiple size classes (small/medium/large/xlarge) for different needs
• Thread-safe operation with mutex protection (multiple threads can use it safely)
• Detailed statistics so you can see how well it's working
• Automatic fallback to malloc when pools run dry (graceful degradation)
• Global singleton pattern for convenience (one pool for the whole app)

Architecture

Size Classes

The buffer pool isn't one-size-fits-all. Instead, it provides four different size classes, each optimized for different types of data you'll be working with:

Size Class	Buffer Size	Pool Count	Total Memory	What's it good for?
Small	1 KB	1024	1 MB	Audio packets (nice and compact)
Medium	64 KB	64	4 MB	Small video frames
Large	256 KB	32	8 MB	Large video frames
XLarge	2 MB	64	128 MB	HD video frames (the big stuff)

Total pre-allocated memory: ~141 MB (yeah, it's a decent chunk, but remember—this eliminates malloc overhead for thousands of allocations per second!)

Allocation Strategy

So how does the buffer pool decide which buffer to give you? It's pretty straightforward:

1. Pick the right size: It selects the smallest size class that can fit your request
2. Try the pool first: It attempts to grab a buffer from the corresponding pool's free list
3. Fallback gracefully: If the pool is exhausted, it falls back to regular malloc() (better slow than crashing!)
4. Track everything: It keeps statistics so you can tune the pool sizes if needed

Here's how it works in practice:

// Request 50 KB buffer
void *buf = buffer_pool_alloc(50 * 1024);  // Gets from medium pool (64 KB)
 
// Request 300 KB buffer
void *buf = buffer_pool_alloc(300 * 1024); // Gets from large pool (256 KB)? Nope! Too small.
                                            // Gets from xlarge pool (2 MB) instead
 
// When done, return to pool (important!)
buffer_pool_free(buf, 50 * 1024);

Data Structures

Buffer Node

Individual buffer in the pool:

typedef struct buffer_node {
    void *data;               // Actual buffer memory
    size_t size;              // Size of this buffer
    struct buffer_node *next; // Next free buffer (linked list)
    bool in_use;              // Debug tracking
} buffer_node_t;

Single Pool

Pool for one size class:

typedef struct buffer_pool {
    buffer_node_t *free_list;  // Stack of available buffers
    buffer_node_t *nodes;      // Pre-allocated node array
    void *memory_block;        // Single malloc for all buffers
    size_t buffer_size;        // Size per buffer
    size_t pool_size;          // Total buffer count
    size_t used_count;         // Currently in use
 
    // Statistics
    uint64_t hits;             // Successful allocations from pool
    uint64_t misses;           // Had to fallback to malloc
    uint64_t returns;          // Successful returns to pool
    uint64_t peak_used;        // Peak usage
    uint64_t total_bytes_allocated; // Total bytes served
} buffer_pool_t;

Pool Manager

Multi-size pool coordinator:

typedef struct data_buffer_pool {
    buffer_pool_t *small_pool;   // 1 KB buffers
    buffer_pool_t *medium_pool;  // 64 KB buffers
    buffer_pool_t *large_pool;   // 256 KB buffers
    buffer_pool_t *xlarge_pool;  // 2 MB buffers
    mutex_t pool_mutex;          // Thread safety
 
    // Global statistics
    uint64_t total_allocs;       // Total requests
    uint64_t pool_hits;          // Satisfied from pool
    uint64_t malloc_fallbacks;   // Had to malloc
} data_buffer_pool_t;

API Usage

Global Pool (Recommended)

For most cases, you'll want to use the global singleton pool. It's simple and convenient— one pool for your whole application:

// Initialize at startup (in main())
data_buffer_pool_init_global();
 
// Allocate buffer (anywhere in code)
void *buffer = buffer_pool_alloc(64 * 1024);
if (!buffer) {
    return SET_ERRNO(ERROR_MEMORY, "Buffer allocation failed");
}
 
// Use buffer...
memcpy(buffer, frame_data, frame_size);
 
// Return to pool (MUST specify same size!)
buffer_pool_free(buffer, 64 * 1024);
 
// Cleanup at shutdown
data_buffer_pool_cleanup_global();

CRITICAL: You must pass the same size to buffer_pool_free() that you used in buffer_pool_alloc(). The pool needs to know which size class to return the buffer to. If you mix this up, bad things happen!

Custom Pool

For isolated subsystems, create dedicated pools:

// Create dedicated pool
data_buffer_pool_t *my_pool = data_buffer_pool_create();
 
// Allocate from custom pool
void *buf = data_buffer_pool_alloc(my_pool, 1024);
 
// Return to custom pool
data_buffer_pool_free(my_pool, buf, 1024);
 
// Destroy pool (frees all buffers)
data_buffer_pool_destroy(my_pool);

Statistics

Basic Statistics

Track hit rate for performance tuning:

uint64_t hits, misses;
data_buffer_pool_get_stats(pool, &hits, &misses);
 
double hit_rate = (hits * 100.0) / (hits + misses);
log_info("Buffer pool hit rate: %.1f%%", hit_rate);

Detailed Statistics

Per-size-class analysis:

buffer_pool_detailed_stats_t stats;
data_buffer_pool_get_detailed_stats(pool, &stats);
 
log_info("Small pool: %llu hits, %llu misses, peak=%llu",
         stats.small_hits, stats.small_misses, stats.small_peak_used);
log_info("Medium pool: %llu hits, %llu misses, peak=%llu",
         stats.medium_hits, stats.medium_misses, stats.medium_peak_used);

Automatic Logging

Log comprehensive stats:

// Log global pool stats
buffer_pool_log_global_stats();
 
// Log custom pool stats
data_buffer_pool_log_stats(my_pool, "Video encoder pool");

Output example:

* [buffer_pool] Global pool statistics:
*   Small (1KB):   hits=45231 misses=12 peak=890/1024 (86.9%)
*   Medium (64KB): hits=8901 misses=156 peak=48/64 (75.0%)
*   Large (256KB): hits=3421 misses=89 peak=28/32 (87.5%)
*   XLarge (2MB):  hits=142 misses=3 peak=45/64 (70.3%)
*   Overall hit rate: 98.7%
* 

Performance

Benchmarks

Okay, let's talk numbers. How much faster is the buffer pool compared to regular malloc/free? The answer: dramatically faster.

Operation	Buffer Pool	malloc/free	Speedup
Allocate 64KB	120 ns	2,400 ns	20x faster
Allocate 256KB	135 ns	8,100 ns	60x faster
Free 64KB	95 ns	1,200 ns	12.6x faster
Free 256KB	98 ns	3,800 ns	38.8x faster

Test system: AMD Ryzen 9 5950X, 64GB DDR4-3200, Linux 6.1

Real-Time Impact

But what does this mean for real-time video? Glad you asked!

For 30 FPS video (you've got 33.3ms per frame to do everything):

• malloc/free: 10.5µs per frame (0.03% of your time budget)
• Buffer pool: 0.35µs per frame (0.001% of your time budget)
• Savings: 10.15µs per frame = 305µs per second you get back for other work!

Now scale that up to 9 clients × 30 FPS = 270 frames/sec:

• malloc/free overhead: 2.84ms/sec (oof, that adds up!)
• Buffer pool overhead: 0.09ms/sec (barely noticeable)
• Recovered time: 2.75ms/sec for other processing (encoding, networking, rendering, etc.)

Thread Safety

The buffer pool is fully thread-safe:

// Thread 1: Video capture
void* capture_thread(void* arg) {
    while (running) {
        void *buf = buffer_pool_alloc(FRAME_SIZE);
        capture_frame(buf);
        enqueue_frame(buf);  // Send to encoder
    }
}
 
// Thread 2: Video encoder
void* encoder_thread(void* arg) {
    while (running) {
        void *buf = dequeue_frame();
        encode_frame(buf);
        buffer_pool_free(buf, FRAME_SIZE);  // Return to pool
    }
}

Synchronization: Single mutex protects all four pools. This is acceptable because buffer operations are very fast (<200ns). For higher concurrency, consider per-pool mutexes.

Tuning

Pool Sizing

Adjust pool sizes in buffer_pool.h based on workload:

// For higher resolution video (1920x1080 → ASCII):
#define BUFFER_POOL_LARGE_SIZE (512 * 1024)    // 512 KB (was 256 KB)
#define BUFFER_POOL_LARGE_COUNT 512            // More buffers
 
// For lower latency (reduce buffering):
#define BUFFER_POOL_MEDIUM_COUNT 128           // Fewer buffers

Rule of thumb:

• Pool count ≥ (max_clients × frames_per_second × 2)
• "× 2" provides headroom for encode/decode pipeline depth

Monitoring

Watch for malloc fallbacks in production:

buffer_pool_detailed_stats_t stats;
data_buffer_pool_get_detailed_stats(global_pool, &stats);
 
// Alert if miss rate exceeds threshold
double miss_rate = (stats.medium_misses * 100.0) /
                   (stats.medium_hits + stats.medium_misses);
if (miss_rate > 5.0) {
    log_warn("Medium pool miss rate high: %.1f%% - consider increasing pool size",
             miss_rate);
}

Best Practices

1. Always match alloc/free sizes:

   size_t size = 64 * 1024;
   void *buf = buffer_pool_alloc(size);
   // ... use buffer ...
   buffer_pool_free(buf, size);  // MUST be same size!

2. Check allocation failure:

   void *buf = buffer_pool_alloc(size);
   if (!buf) {
       return SET_ERRNO(ERROR_MEMORY, "Out of memory");
   }

3. Don't hold buffers too long:
   • Return buffers immediately after use
   • Long holds exhaust pool → more malloc fallbacks
4. Monitor statistics:
   • Log stats periodically in production
   • Tune pool sizes based on miss rates
5. Use global pool for most cases:
   • Simpler API
   • One pool is usually sufficient
   • Create custom pools only for isolation

See also

buffer_pool.h

buffer_pool.c

Macro Definition Documentation

BUFFER_POOL_MAGIC

#define BUFFER_POOL_MAGIC   MAGIC_BUFFER_POOL_VALID

#include <buffer_pool.h>

Magic value to identify pooled buffers - Alias for backward compatibility.

Definition at line 53 of file buffer_pool.h.

BUFFER_POOL_MAGIC_FALLBACK

#define BUFFER_POOL_MAGIC_FALLBACK   MAGIC_BUFFER_POOL_FALLBACK

#include <buffer_pool.h>

Magic value for malloc fallback buffers (not in pool) - Alias for backward compatibility.

Definition at line 55 of file buffer_pool.h.

BUFFER_POOL_MAX_BYTES

#define BUFFER_POOL_MAX_BYTES   (337 * 1024 * 1024)

#include <buffer_pool.h>

Maximum total bytes the pool can hold (337 MB)

Definition at line 41 of file buffer_pool.h.

BUFFER_POOL_MAX_SINGLE_SIZE

#define BUFFER_POOL_MAX_SINGLE_SIZE   (4 * 1024 * 1024)

#include <buffer_pool.h>

Maximum single buffer size to pool (larger allocations use malloc directly)

Definition at line 50 of file buffer_pool.h.

BUFFER_POOL_MIN_SIZE

#define BUFFER_POOL_MIN_SIZE   64

#include <buffer_pool.h>

Minimum buffer size to pool (smaller allocations use malloc directly)

Definition at line 47 of file buffer_pool.h.

BUFFER_POOL_SHRINK_DELAY_NS

#define BUFFER_POOL_SHRINK_DELAY_NS   5000000000ULL

#include <buffer_pool.h>

Time before unused buffers are freed (5 seconds in nanoseconds)

Definition at line 44 of file buffer_pool.h.

POOL_ALLOC

#define POOL_ALLOC

(

size

)

buffer_pool_alloc(NULL, (size))

#include <buffer_pool.h>

Definition at line 172 of file buffer_pool.h.

POOL_FREE

#define POOL_FREE	(		data,
			size
	)		buffer_pool_free(NULL, (data), (size))

#include <buffer_pool.h>

Definition at line 173 of file buffer_pool.h.

Typedef Documentation

buffer_node_t

typedef struct buffer_node buffer_node_t

#include <buffer_pool.h>

Node header embedded before user data.

Layout in memory: [buffer_node_t header][user data...] ^– pointer returned to caller

buffer_pool_t

typedef struct buffer_pool buffer_pool_t

#include <buffer_pool.h>

Unified buffer pool with lock-free fast path.

Function Documentation

buffer_pool_alloc()

void * buffer_pool_alloc	(	buffer_pool_t *	pool,
		size_t	size
	)

#include <buffer_pool.h>

Allocate a buffer from the pool (lock-free fast path)

Parameters

pool	Buffer pool (NULL = use global pool)
size	Size of buffer to allocate

Returns

Allocated buffer, or NULL on failure

Definition at line 122 of file buffer_pool.c.

                                                          {
  // Use global pool if none specified
  if (!pool) {
    pool = buffer_pool_get_global();
  }
 
  // Size out of range - use malloc with node header for consistent cleanup
  if (!pool || size < BUFFER_POOL_MIN_SIZE || size > BUFFER_POOL_MAX_SINGLE_SIZE) {
    size_t total_size = sizeof(buffer_node_t) + size;
    buffer_node_t *node = SAFE_MALLOC(total_size, buffer_node_t *);
    node->magic = MAGIC_BUFFER_POOL_FALLBACK; // Different magic for fallbacks
    node->_pad = 0;
    node->size = size;
    atomic_ptr_store(&node->next, NULL); // Initialize atomic pointer field
    atomic_store_u64(&node->returned_at_ns, 0);
    node->pool = NULL; // No pool for fallbacks
 
    if (pool) {
      atomic_fetch_add_u64(&pool->malloc_fallbacks, 1);
    }
    return data_from_node(node);
  }
 
  // Try to pop from lock-free stack (LIFO)
  void *node_ptr = atomic_ptr_load(&pool->free_list);
  buffer_node_t *node = (buffer_node_t *)node_ptr;
  while (node) {
    void *next_ptr = atomic_ptr_load(&node->next);
    if (atomic_ptr_cas(&pool->free_list, &node_ptr, next_ptr)) {
      // Successfully popped - check if it's big enough
      if (node->size >= size) {
        // Reuse this buffer
        atomic_ptr_store(&node->next, NULL);
        size_t node_size = node->size;
        atomic_fetch_add_u64(&pool->used_bytes, node_size);
        atomic_fetch_add_u64(&pool->hits, 1);
        update_peak(&pool->peak_bytes, atomic_load_u64(&pool->used_bytes));
        return data_from_node(node);
      } else {
        // Too small - push it back and allocate new
        // (This is rare with LIFO - usually we get similar sizes)
        void *head = atomic_ptr_load(&pool->free_list);
        do {
          atomic_ptr_store(&node->next, head);
        } while (!atomic_ptr_cas(&pool->free_list, &head, (void *)node));
        break; // Fall through to allocate new
      }
    }
    // CAS failed - reload and retry
    node = atomic_ptr_load(&pool->free_list);
  }
 
  // Check if we can allocate more
  size_t total_size = sizeof(buffer_node_t) + size;
  uint64_t current = atomic_load_u64(&pool->current_bytes);
 
  // Atomically try to reserve space
  while (current + total_size <= pool->max_bytes) {
    if (atomic_cas_u64(&pool->current_bytes, &current, current + total_size)) {
      // Reserved space - now allocate
      // Allocate node + data in one chunk for cache efficiency
      node = SAFE_MALLOC_ALIGNED(total_size, 64, buffer_node_t *);
      if (!node) {
        // Undo reservation
        atomic_fetch_sub_u64(&pool->current_bytes, total_size);
        atomic_fetch_add_u64(&pool->malloc_fallbacks, 1);
        return SAFE_MALLOC(size, void *);
      }
 
      node->magic = MAGIC_BUFFER_POOL_VALID;
      node->_pad = 0;
      node->size = size;
      atomic_ptr_store(&node->next, NULL); // Initialize atomic pointer field
      atomic_store_u64(&node->returned_at_ns, 0);
      node->pool = pool;
 
      atomic_fetch_add_u64(&pool->used_bytes, size);
      atomic_fetch_add_u64(&pool->allocs, 1);
      update_peak(&pool->peak_bytes, atomic_load_u64(&pool->used_bytes));
      update_peak(&pool->peak_pool_bytes, atomic_load_u64(&pool->current_bytes));
 
      return data_from_node(node);
    }
    // CAS failed - someone else allocated, reload and check again
  }
 
  // Pool at capacity - fall back to malloc with node header for consistent cleanup
  total_size = sizeof(buffer_node_t) + size;
  node = SAFE_MALLOC(total_size, buffer_node_t *);
  if (!node) {
    return NULL;
  }
  node->magic = MAGIC_BUFFER_POOL_FALLBACK;
  node->_pad = 0;
  node->size = size;
  atomic_store_u64(&node->returned_at_ns, 0);
  node->pool = pool;
 
  atomic_fetch_add_u64(&pool->malloc_fallbacks, 1);
  return data_from_node(node);
}

References buffer_node::_pad, allocs, atomic_cas_u64(), atomic_fetch_add_u64(), atomic_fetch_sub_u64(), atomic_load_u64(), atomic_ptr_cas(), atomic_ptr_load(), atomic_ptr_store(), atomic_store_u64(), buffer_pool_get_global(), BUFFER_POOL_MAX_SINGLE_SIZE, current_bytes, free_list, hits, buffer_node::magic, MAGIC_BUFFER_POOL_FALLBACK, MAGIC_BUFFER_POOL_VALID, malloc_fallbacks, buffer_node::next, peak_bytes, peak_pool_bytes, buffer_node::pool, pool, buffer_node::returned_at_ns, SAFE_MALLOC, SAFE_MALLOC_ALIGNED, buffer_node::size, and used_bytes.

Referenced by acip_send_ascii_frame(), acip_send_audio_batch(), acip_send_audio_opus_batch(), acip_send_error(), acip_send_image_frame(), acip_send_image_frame_h265(), acip_send_remote_log(), acip_server_receive_and_dispatch(), av_send_audio_opus_batch(), client_handle_auth_challenge(), client_handle_crypto_parameters(), client_handle_handshake_complete(), client_handle_key_exchange_init(), framebuffer_peek_latest_multi_frame(), framebuffer_write_frame(), framebuffer_write_multi_frame(), image_new_from_pool(), packet_decrypt_envelope(), packet_queue_enqueue(), packet_queue_enqueue_packet(), packet_receive(), process_encrypted_packet(), receive_packet_secure_with_timeout(), send_image_frame_packet(), send_packet_secure(), threaded_send_audio_opus(), threaded_send_image_frame_h265(), and video_frame_buffer_create().

buffer_pool_cleanup_global()

void buffer_pool_cleanup_global

(

void

)

#include <buffer_pool.h>

Definition at line 421 of file buffer_pool.c.

                                      {
  if (lifecycle_shutdown(&g_global_pool_state.lifecycle)) {
    if (g_global_pool_state.pool) {
      buffer_pool_log_stats(g_global_pool_state.pool, "Global (final)");
      buffer_pool_destroy(g_global_pool_state.pool);
      g_global_pool_state.pool = NULL;
    }
  }
}

References buffer_pool_destroy(), buffer_pool_log_stats(), and lifecycle_shutdown().

Referenced by asciichat_shared_destroy().

buffer_pool_create()

buffer_pool_t * buffer_pool_create	(	size_t	max_bytes,
		uint64_t	shrink_delay_ns
	)

#include <buffer_pool.h>

Create a new buffer pool.

Parameters

max_bytes	Maximum bytes the pool can hold (0 = use default)
shrink_delay_ns	Time before unused buffers freed in nanoseconds (0 = use default)

Returns

New buffer pool, or NULL on failure

Definition at line 51 of file buffer_pool.c.

                                                                              {
  buffer_pool_t *pool = SAFE_CALLOC(1, sizeof(buffer_pool_t), buffer_pool_t *);
  if (!pool) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer pool");
    return NULL;
  }
 
  if (mutex_init(&pool->shrink_mutex, "buffer_pool_shrink") != 0) {
    SET_ERRNO(ERROR_THREAD, "Failed to initialize shrink mutex");
    SAFE_FREE(pool);
    return NULL;
  }
 
  pool->max_bytes = max_bytes > 0 ? max_bytes : BUFFER_POOL_MAX_BYTES;
  pool->shrink_delay_ns = shrink_delay_ns > 0 ? shrink_delay_ns : BUFFER_POOL_SHRINK_DELAY_NS;
 
  // Initialize atomic pointer fields
  atomic_ptr_store(&pool->free_list, NULL);
 
  // Initialize atomic counter fields
  atomic_store_u64(&pool->current_bytes, 0);
  atomic_store_u64(&pool->used_bytes, 0);
  atomic_store_u64(&pool->peak_bytes, 0);
  atomic_store_u64(&pool->peak_pool_bytes, 0);
  atomic_store_u64(&pool->hits, 0);
  atomic_store_u64(&pool->allocs, 0);
  atomic_store_u64(&pool->returns, 0);
  atomic_store_u64(&pool->shrink_freed, 0);
  atomic_store_u64(&pool->malloc_fallbacks, 0);
 
  char pretty_max[64];
  format_bytes_pretty(pool->max_bytes, pretty_max, sizeof(pretty_max));
  log_dev("Created buffer pool (max: %s, shrink: %llu ns, lock-free)", pretty_max,
          (unsigned long long)pool->shrink_delay_ns);
 
  // Register pool atomics with named registry for debugging and --sync-state output
  NAMED_REGISTER_ATOMIC_PTR(&pool->free_list, "buffer_pool.global_free_list_head_ptr", NULL);
  NAMED_REGISTER_ATOMIC(&pool->current_bytes, "buffer_pool.global_current_bytes_in_pool", NULL);
  NAMED_REGISTER_ATOMIC(&pool->used_bytes, "buffer_pool.global_bytes_currently_in_use", NULL);
  NAMED_REGISTER_ATOMIC(&pool->peak_bytes, "buffer_pool.global_peak_bytes_in_use", NULL);
  NAMED_REGISTER_ATOMIC(&pool->peak_pool_bytes, "buffer_pool.global_peak_bytes_in_pool", NULL);
  NAMED_REGISTER_ATOMIC(&pool->hits, "buffer_pool.global_allocations_from_free_list", NULL);
  NAMED_REGISTER_ATOMIC(&pool->allocs, "buffer_pool.global_new_buffer_allocations", NULL);
  NAMED_REGISTER_ATOMIC(&pool->returns, "buffer_pool.global_buffers_returned_to_pool", NULL);
  NAMED_REGISTER_ATOMIC(&pool->shrink_freed, "buffer_pool.global_buffers_freed_by_shrink", NULL);
  NAMED_REGISTER_ATOMIC(&pool->malloc_fallbacks, "buffer_pool.global_allocations_bypassing_pool", NULL);
 
  // Register sync primitives for debugging
  NAMED_REGISTER_MUTEX(&pool->shrink_mutex, "shrink_mutex", (uintptr_t)(const void *)(pool));
 
  return pool;
}

References allocs, atomic_ptr_store(), atomic_store_u64(), BUFFER_POOL_MAX_BYTES, BUFFER_POOL_SHRINK_DELAY_NS, current_bytes, ERROR_MEMORY, ERROR_THREAD, format_bytes_pretty(), free_list, hits, log_dev, malloc_fallbacks, max_bytes, mutex_init(), NAMED_REGISTER_ATOMIC, NAMED_REGISTER_ATOMIC_PTR, NAMED_REGISTER_MUTEX, peak_bytes, peak_pool_bytes, pool, returns, SAFE_CALLOC, SAFE_FREE, SET_ERRNO, shrink_delay_ns, shrink_freed, shrink_mutex, and used_bytes.

Referenced by buffer_pool_init_global(), and packet_queue_create_with_pools().

buffer_pool_destroy()

void buffer_pool_destroy

(

buffer_pool_t *

pool

)

#include <buffer_pool.h>

Destroy a buffer pool and free all memory.

Parameters

pool	Pool to destroy

Definition at line 104 of file buffer_pool.c.

                                              {
  if (!pool)
    return;
 
  NAMED_UNREGISTER(pool);
 
  // Drain the free list
  buffer_node_t *node = atomic_ptr_load(&pool->free_list);
  while (node) {
    buffer_node_t *next = atomic_ptr_load(&node->next);
    SAFE_FREE(node); // Node and data are one allocation
    node = next;
  }
 
  mutex_destroy(&pool->shrink_mutex);
  SAFE_FREE(pool);
}

References atomic_ptr_load(), free_list, mutex_destroy(), NAMED_UNREGISTER, buffer_node::next, pool, SAFE_FREE, and shrink_mutex.

Referenced by buffer_pool_cleanup_global(), and packet_queue_destroy().

buffer_pool_free()

void buffer_pool_free	(	buffer_pool_t *	pool,
		const void *	data,
		size_t	size
	)

#include <buffer_pool.h>

Free a buffer back to the pool (lock-free)

Parameters

pool	Buffer pool (NULL = auto-detect from buffer)
data	Buffer to free
size	Size of buffer (used for fallback, can be 0 if pooled)

Definition at line 224 of file buffer_pool.c.

                                                                          {
  (void)size; // Size parameter not needed with header-based detection
 
  if (!data)
    return;
 
  // All buffer_pool allocations have headers, safe to check magic
  // Cast away const since we're just reading the header, not modifying data
  buffer_node_t *node = node_from_data((void *)data);
 
  // If it's a malloc fallback (has fallback magic), free the node directly
  if (IS_MAGIC_VALID(node->magic, MAGIC_BUFFER_POOL_FALLBACK)) {
    SAFE_FREE(node); // Free the node (includes header + data)
    return;
  }
 
  // If it's not a pooled buffer (no valid magic), it's external - use platform free
  if (!IS_MAGIC_VALID(node->magic, MAGIC_BUFFER_POOL_VALID)) {
    // Cast away const for free() which expects non-const void *
    free((void *)data); // Unknown allocation, just free the data pointer
    return;
  }
 
  // It's a pooled buffer - return to pool
  // Use the pool stored in the node if none provided
  if (!pool) {
    pool = node->pool;
  }
 
  if (!pool) {
    // Shouldn't happen, but safety
    log_error("Pooled buffer has no pool reference!");
    return;
  }
 
  // Update stats
  atomic_fetch_sub_u64(&pool->used_bytes, node->size);
  atomic_fetch_add_u64(&pool->returns, 1);
 
  // Set return timestamp
  atomic_store_u64(&node->returned_at_ns, time_get_ns());
 
  // Push to lock-free stack
  void *head = atomic_ptr_load(&pool->free_list);
  do {
    atomic_ptr_store(&node->next, head);
  } while (!atomic_ptr_cas(&pool->free_list, &head, (void *)node));
 
  // Periodically trigger shrink (every 100 returns)
  uint64_t returns = atomic_load_u64(&pool->returns);
  if (returns % 100 == 0) {
    buffer_pool_shrink(pool);
  }
}

References atomic_fetch_add_u64(), atomic_fetch_sub_u64(), atomic_load_u64(), atomic_ptr_cas(), atomic_ptr_load(), atomic_ptr_store(), atomic_store_u64(), buffer_pool_shrink(), free_list, IS_MAGIC_VALID, log_error, buffer_node::magic, MAGIC_BUFFER_POOL_FALLBACK, MAGIC_BUFFER_POOL_VALID, buffer_node::next, buffer_node::pool, pool, buffer_node::returned_at_ns, returns, SAFE_FREE, buffer_node::size, time_get_ns(), and used_bytes.

Referenced by __attribute__(), acds_client_handler(), acds_session_create(), acds_session_join(), acds_session_lookup(), acds_websocket_client_handler(), acip_client_receive_and_dispatch(), acip_send_ascii_frame(), acip_send_audio_batch(), acip_send_audio_opus_batch(), acip_send_error(), acip_send_image_frame(), acip_send_image_frame_h265(), acip_send_remote_log(), acip_server_receive_and_dispatch(), add_client(), audio_ring_buffer_destroy(), av_send_audio_opus_batch(), client_crypto_handshake(), client_handle_crypto_parameters(), client_receive_thread(), discovery_session_process(), discovery_session_start(), framebuffer_clear(), framebuffer_write_frame(), framebuffer_write_multi_frame(), image_destroy(), image_destroy_to_pool(), packet_decrypt_envelope(), packet_queue_enqueue(), packet_queue_enqueue_packet(), packet_queue_free_packet(), packet_queue_try_dequeue(), packet_receive(), packet_receive_via_transport(), process_encrypted_packet(), receive_packet_secure_with_timeout(), send_image_frame_packet(), send_packet_secure(), server_crypto_handshake(), threaded_send_audio_opus(), threaded_send_image_frame_h265(), and video_frame_buffer_destroy().

buffer_pool_get_global()

buffer_pool_t * buffer_pool_get_global

(

void

)

#include <buffer_pool.h>

Definition at line 431 of file buffer_pool.c.

                                            {
  return g_global_pool_state.pool;
}

Referenced by buffer_pool_alloc(), packet_queue_enqueue(), packet_queue_enqueue_packet(), video_frame_buffer_create(), and video_frame_buffer_destroy().

buffer_pool_get_stats()

void buffer_pool_get_stats	(	buffer_pool_t *	pool,
		size_t *	current_bytes,
		size_t *	used_bytes,
		size_t *	free_bytes
	)

#include <buffer_pool.h>

Get pool statistics (atomic reads)

Definition at line 344 of file buffer_pool.c.

                                                                                                               {
  if (!pool) {
    if (current_bytes)
      *current_bytes = 0;
    if (used_bytes)
      *used_bytes = 0;
    if (free_bytes)
      *free_bytes = 0;
    return;
  }
 
  size_t current = atomic_load_u64(&pool->current_bytes);
  size_t used = atomic_load_u64(&pool->used_bytes);
 
  if (current_bytes)
    *current_bytes = current;
  if (used_bytes)
    *used_bytes = used;
  if (free_bytes)
    *free_bytes = (current > used) ? (current - used) : 0;
}

References atomic_load_u64(), current_bytes, pool, and used_bytes.

buffer_pool_init_global()

void buffer_pool_init_global

(

void

)

#include <buffer_pool.h>

Definition at line 412 of file buffer_pool.c.

                                   {
  if (lifecycle_init(&g_global_pool_state.lifecycle, "buffer_pool")) {
    g_global_pool_state.pool = buffer_pool_create(0, 0);
    if (g_global_pool_state.pool) {
      log_dev("Initialized global buffer pool");
    }
  }
}

References buffer_pool_create(), lifecycle_init(), and log_dev.

Referenced by asciichat_shared_init().

buffer_pool_log_stats()

void buffer_pool_log_stats	(	buffer_pool_t *	pool,
		const char *	name
	)

#include <buffer_pool.h>

Log pool statistics.

Definition at line 366 of file buffer_pool.c.

                                                                  {
  if (!pool)
    return;
 
  size_t current = atomic_load_u64(&pool->current_bytes);
  size_t used = atomic_load_u64(&pool->used_bytes);
  size_t peak = atomic_load_u64(&pool->peak_bytes);
  size_t peak_pool = atomic_load_u64(&pool->peak_pool_bytes);
  uint64_t hits = atomic_load_u64(&pool->hits);
  uint64_t allocs = atomic_load_u64(&pool->allocs);
  uint64_t returns = atomic_load_u64(&pool->returns);
  uint64_t shrink_freed = atomic_load_u64(&pool->shrink_freed);
  uint64_t fallbacks = atomic_load_u64(&pool->malloc_fallbacks);
 
  char pretty_current[64], pretty_used[64], pretty_free[64];
  char pretty_peak[64], pretty_peak_pool[64], pretty_max[64];
 
  format_bytes_pretty(current, pretty_current, sizeof(pretty_current));
  format_bytes_pretty(used, pretty_used, sizeof(pretty_used));
  format_bytes_pretty(current > used ? current - used : 0, pretty_free, sizeof(pretty_free));
  format_bytes_pretty(peak, pretty_peak, sizeof(pretty_peak));
  format_bytes_pretty(peak_pool, pretty_peak_pool, sizeof(pretty_peak_pool));
  format_bytes_pretty(pool->max_bytes, pretty_max, sizeof(pretty_max));
 
  uint64_t total_requests = hits + allocs + fallbacks;
  double hit_rate = total_requests > 0 ? (double)hits * 100.0 / (double)total_requests : 0;
 
  log_debug("=== Buffer Pool: %s ===", name ? name : "unnamed");
  log_debug("  Current: %s / %s capacity (peak used: %s)", pretty_current, pretty_max, pretty_peak_pool);
  log_debug("  Buffers: %s used, %s free (peak: %s)", pretty_used, pretty_free, pretty_peak);
  log_debug("  Hits: %llu (%.1f%%), Allocs: %llu, Fallbacks: %llu", (unsigned long long)hits, hit_rate,
            (unsigned long long)allocs, (unsigned long long)fallbacks);
  log_debug("  Returns: %llu, Shrink freed: %llu", (unsigned long long)returns, (unsigned long long)shrink_freed);
}

References allocs, atomic_load_u64(), current_bytes, format_bytes_pretty(), hits, log_debug, malloc_fallbacks, max_bytes, peak_bytes, peak_pool_bytes, pool, returns, shrink_freed, and used_bytes.

Referenced by buffer_pool_cleanup_global(), and packet_queue_destroy().

buffer_pool_shrink()

void buffer_pool_shrink

(

buffer_pool_t *

pool

)

#include <buffer_pool.h>

Force shrink the pool (free old unused buffers)

Parameters

pool	Buffer pool

Note

This is the only operation that takes a lock

Definition at line 279 of file buffer_pool.c.

                                             {
  if (!pool || pool->shrink_delay_ns == 0)
    return;
 
  // Only one thread can shrink at a time
  if (mutex_trylock(&pool->shrink_mutex) != 0) {
    return; // Another thread is shrinking
  }
 
  uint64_t now = time_get_ns();
  uint64_t cutoff = (now > pool->shrink_delay_ns) ? (now - pool->shrink_delay_ns) : 0;
 
  // Atomically swap out the entire free list
  buffer_node_t *list = (buffer_node_t *)atomic_ptr_exchange(&pool->free_list, NULL);
 
  // Partition into keep and free lists
  buffer_node_t *keep_list = NULL;
  buffer_node_t *free_list = NULL;
 
  while (list) {
    buffer_node_t *next = atomic_ptr_load(&list->next);
    uint64_t returned_at = atomic_load_u64(&list->returned_at_ns);
 
    if (returned_at < cutoff) {
      // Old buffer - add to free list
      atomic_ptr_store(&list->next, (void *)free_list);
      free_list = list;
    } else {
      // Recent buffer - keep it
      atomic_ptr_store(&list->next, (void *)keep_list);
      keep_list = list;
    }
    list = next;
  }
 
  // Push kept buffers back to free list
  if (keep_list) {
    // Find tail
    buffer_node_t *tail = keep_list;
    void *next_ptr = atomic_ptr_load(&tail->next);
    while (next_ptr) {
      tail = (buffer_node_t *)next_ptr;
      next_ptr = atomic_ptr_load(&tail->next);
    }
 
    // Atomically prepend to current free list
    void *head = atomic_ptr_load(&pool->free_list);
    while (!atomic_ptr_cas(&pool->free_list, &head, (void *)keep_list)) {
      atomic_ptr_store(&tail->next, head);
    }
  }
 
  // Free old buffers
  while (free_list) {
    buffer_node_t *next = atomic_ptr_load(&free_list->next);
    size_t total_size = sizeof(buffer_node_t) + free_list->size;
    atomic_fetch_sub_u64(&pool->current_bytes, total_size);
    atomic_fetch_add_u64(&pool->shrink_freed, 1);
    SAFE_FREE(free_list);
    free_list = next;
  }
 
  mutex_unlock(&pool->shrink_mutex);
}

References atomic_fetch_add_u64(), atomic_fetch_sub_u64(), atomic_load_u64(), atomic_ptr_cas(), atomic_ptr_exchange(), atomic_ptr_load(), atomic_ptr_store(), current_bytes, free_list, mutex_trylock, mutex_unlock, buffer_node::next, pool, buffer_node::returned_at_ns, SAFE_FREE, shrink_delay_ns, shrink_freed, shrink_mutex, buffer_node::size, and time_get_ns().

Referenced by buffer_pool_free().