Module buffer_pool 

Zero-Copy Buffer Pool

High-performance buffer management for Rivven with:

• Slab Allocation: Pre-allocated buffers to avoid runtime allocation
• Size Classes: Different buffer sizes for optimal memory usage
• Thread-Local Caching: Reduce contention in hot paths
• Reference Counting: Safe buffer sharing without copies

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Buffer Pool                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │  Small   │  │  Medium  │  │  Large   │  │   Huge (alloc)   │ │
│  │  <= 4KB  │  │  <= 64KB │  │  <= 1MB  │  │   > 1MB          │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬─────────┘ │
│       │              │              │                │          │
│       └──────────────┴──────────────┴────────────────┘          │
│                           │                                      │
│              ┌────────────▼────────────┐                        │
│              │    Thread-Local Cache    │                        │
│              │   (lock-free fast path)  │                        │
│              └────────────┬────────────┘                        │
│                           │                                      │
│              ┌────────────▼────────────┐                        │
│              │    Global Pool (CAS)     │                        │
│              └─────────────────────────┘                        │
└─────────────────────────────────────────────────────────────────┘

Performance Characteristics

• Allocation: O(1) for cached sizes
• Deallocation: O(1) (return to pool)
• Memory overhead: ~4 bytes per buffer (ref count)
• Contention: Near-zero with thread-local caching

Structs

AlignedBuffer

Buffer aligned for direct I/O (O_DIRECT) Required alignment is typically 512 bytes or 4KB

BufferChain

A chain of buffers for scatter-gather I/O

BufferPool

Global buffer pool with size-class segregation

BufferPoolConfig

Buffer pool configuration

PoolStats

Buffer pool statistics

PooledBuffer

A buffer handle that returns to the pool on drop

Enums

SizeClass

Buffer size classes