Template Class PoolAllocator¶

Defined in File pool_allocator.h

Class Documentation¶

template<typename T, size_t C, typename L = SpinLock> class PoolAllocator¶

Fixed-size object pool with O(1) allocation/deallocation using embedded freelist.

PoolAllocator pre-allocates a fixed buffer for C instances of type T and manages them using a freelist embedded directly in the free blocks. This makes allocation and deallocation O(1) pointer operations with LIFO reuse (last freed is first allocated), which tends to have good cache characteristics.

The freelist works by storing pointers to the next free block inside each free block itself. This is why the constraint sizeof(T) >= sizeof(void*) exists: each free block must be large enough to hold a pointer to the next free block. Types smaller than a pointer (like bool, char, uint16_t on 64-bit systems) cannot be pooled with this allocator.

Thread Safety: Controlled by template parameter L. By default uses SpinLock, which is ideal for very short-lived locks (microseconds) with rare contention. For longer critical sections or higher contention, substitute std::mutex: PoolAllocator<MyType, 1000, std::mutex>.

Example - Particle system with object pooling:

PoolAllocator<Particle, 1000> particle_pool;

void spawn_particle(Vector3 pos, Vector3 vel) {
    auto* particle = particle_pool.alloc(pos, vel);  // O(1) allocation
    active_particles.push_back(particle);
}

void update_particles(float dt) {
    for (auto it = active_particles.begin(); it != active_particles.end();) {
        (*it)->update(dt);
        if ((*it)->is_dead()) {
            particle_pool.free(*it);  // O(1) deallocation, returns to freelist
            it = active_particles.erase(it);
        } else {
            ++it;
        }
    }
}

Important Notes:

Allocation throws std::bad_alloc when pool is exhausted (all C slots used)
clear() rebuilds freelist WITHOUT calling destructors - only use when pool is empty or all objects are trivially destructible
Freelist reuse is LIFO order (last freed, first allocated)
Pool memory is never deallocated until PoolAllocator is destroyed