helios::memory::PoolAllocator Class Reference

Pool allocator for fixed-size allocations. More...

#include <pool_allocator.hpp>

Public Member Functions
	PoolAllocator (size_t block_size, size_t block_count, size_t alignment=kDefaultAlignment)
	Constructs a pool allocator.
	PoolAllocator (const PoolAllocator &)=delete
	PoolAllocator (PoolAllocator &&other) noexcept
	~PoolAllocator () noexcept
PoolAllocator &	operator= (const PoolAllocator &)=delete
PoolAllocator &	operator= (PoolAllocator &&other) noexcept
AllocationResult	Allocate (size_t size) noexcept
	Allocates a block from the pool.
template<typename T >
T *	Allocate () noexcept
template<typename T , typename... Args> requires std::constructible_from<T, Args...>
T *	AllocateAndConstruct (Args &&... args) noexcept(std::is_nothrow_constructible_v< T, Args... >)
void	Deallocate (void *ptr) noexcept
	Deallocates a block back to the pool.
void	Reset () noexcept
	Resets the pool, making all blocks available.
bool	Full () const noexcept
	Checks if the allocator is full.
bool	Empty () const noexcept
bool	Owns (const void *ptr) const noexcept
	Checks if a pointer belongs to this pool.
AllocatorStats	Stats () const noexcept
	Gets current allocator statistics.
size_t	BlockSize () const noexcept
	Gets the block size.
size_t	BlockCount () const noexcept
	Gets the block count.
size_t	Capacity () const noexcept
	Gets the total capacity of the pool.
size_t	FreeBlockCount () const noexcept
	Gets the number of free blocks.
size_t	UsedBlockCount () const noexcept
	Gets the number of used blocks.

Static Public Member Functions
template<typename T >
static PoolAllocator	ForType (size_t block_count)

Detailed Description

Pool allocator for fixed-size allocations.

Allocates objects of a fixed size from a pre-allocated pool. Extremely efficient for scenarios where many objects of the same size are allocated and deallocated frequently.

Uses a lock-free free list to track available slots. Each free slot stores a pointer to the next free slot, forming a linked list through the free blocks.

Supports proper deallocation and reuse of freed blocks.

Uses lock-free atomic operations for allocation/deallocation, providing excellent performance in multi-threaded scenarios.

Note

Thread-safe with lock-free operations. All allocations must be the same size (or smaller than block_size).

Definition at line 36 of file pool_allocator.hpp.

Constructor & Destructor Documentation

PoolAllocator() [1/3]

helios::memory::PoolAllocator::PoolAllocator ( size_t  block_size, size_t  block_count, size_t  alignment = kDefaultAlignment  )

inline

Constructs a pool allocator.

Warning

Triggers assertion in next cases:

• Block count is 0.
• Alignment is not a power of 2.
• Alignment is less than alignof(void*).

Parameters

block_size	Size of each block in bytes (minimum 8 bytes for free list pointer)
block_count	Number of blocks to allocate
alignment	Alignment for each block (must be power of 2)

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 210 of file pool_allocator.hpp.

    : block_size_(std::max(block_size, sizeof(void*))),  // Minimum size for free list pointer
      block_count_(block_count),
      alignment_(alignment),
      free_block_count_{block_count} {
  HELIOS_ASSERT(block_count_ > 0, "Failed to construct PoolAllocator: block_count must be greater than 0!, got '{}'",
                block_count_);
  HELIOS_ASSERT(IsPowerOfTwo(alignment), "Failed to construct PoolAllocator: alignment must be power of 2, got '{}'!",
                alignment);
  HELIOS_ASSERT(alignment >= alignof(void*),
                "Failed to construct PoolAllocator: alignment must be at least '{}', got '{}'!", alignof(void*),
                alignment);
 
  // Align block size to alignment
  block_size_ = AlignUp(block_size_, alignment_);
  capacity_ = block_size_ * block_count_;
 
  // Allocate aligned buffer
  buffer_ = AlignedAlloc(alignment_, capacity_);
  HELIOS_VERIFY(buffer_ != nullptr, "Failed to construct PoolAllocator: Allocation of buffer failed!");
 
  InitializeFreeList();
  free_list_head_atomic_.store(free_list_head_, std::memory_order_release);
}

PoolAllocator() [2/3]

helios::memory::PoolAllocator::PoolAllocator ( const PoolAllocator &  )

delete

PoolAllocator() [3/3]

helios::memory::PoolAllocator::PoolAllocator ( PoolAllocator &&  other )

inlinenoexcept

Definition at line 235 of file pool_allocator.hpp.

    : buffer_(other.buffer_),
      free_list_head_(other.free_list_head_),
      block_size_(other.block_size_),
      block_count_(other.block_count_),
      capacity_(other.capacity_),
      alignment_(other.alignment_),
      free_list_head_atomic_{other.free_list_head_atomic_.load(std::memory_order_acquire)},
      free_block_count_{other.free_block_count_.load(std::memory_order_acquire)},
      peak_used_blocks_{other.peak_used_blocks_.load(std::memory_order_acquire)},
      total_allocations_{other.total_allocations_.load(std::memory_order_acquire)},
      total_deallocations_{other.total_deallocations_.load(std::memory_order_acquire)} {
  other.buffer_ = nullptr;
  other.free_list_head_ = nullptr;
  other.block_size_ = 0;
  other.block_count_ = 0;
  other.capacity_ = 0;
  other.alignment_ = 0;
  other.free_list_head_atomic_.store(nullptr, std::memory_order_release);
  other.free_block_count_.store(0, std::memory_order_release);
  other.peak_used_blocks_.store(0, std::memory_order_release);
  other.total_allocations_.store(0, std::memory_order_release);
  other.total_deallocations_.store(0, std::memory_order_release);
}

~PoolAllocator()

helios::memory::PoolAllocator::~PoolAllocator ( )

inlinenoexcept

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 260 of file pool_allocator.hpp.

                                              {
  if (buffer_ != nullptr) {
    AlignedFree(buffer_);
  }
}

Member Function Documentation

Allocate() [1/2]

template<typename T >

T * helios::memory::PoolAllocator::Allocate ( )

inlinenoexcept

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 428 of file pool_allocator.hpp.

                                           {
  auto result = Allocate(sizeof(T));
  return static_cast<T*>(result.ptr);
}

Allocate() [2/2]

AllocationResult helios::memory::PoolAllocator::Allocate ( size_t  size )

inlinenoexcept

Allocates a block from the pool.

Note

Size is ignored but kept for interface compatibility.

Warning

Triggers assertion if size exceeds block_size.

Parameters

size	Number of bytes to allocate (must be <= block_size)

Returns

AllocationResult with pointer and actual allocated size, or {nullptr, 0} on failure

Definition at line 305 of file pool_allocator.hpp.

                                                                    {
  if (size == 0) [[unlikely]] {
    return {.ptr = nullptr, .allocated_size = 0};
  }
 
  HELIOS_ASSERT(size <= block_size_, "Failed to allocate memory: size '{}' exceeds block size '{}'!", size,
                block_size_);
 
  // Lock-free allocation using compare-and-swap
  void* old_head = free_list_head_atomic_.load(std::memory_order_acquire);
  void* new_head = nullptr;
 
  do {
    // Check if we have free blocks
    if (old_head == nullptr) {
      return {.ptr = nullptr, .allocated_size = 0};
    }
 
    // Read the next pointer from the old head
    new_head = *reinterpret_cast<void**>(old_head);
 
    // Try to atomically update the head pointer
  } while (!free_list_head_atomic_.compare_exchange_weak(old_head, new_head, std::memory_order_release,
                                                         std::memory_order_acquire));
 
  // Successfully allocated - update counters
  free_block_count_.fetch_sub(1, std::memory_order_relaxed);
  total_allocations_.fetch_add(1, std::memory_order_relaxed);
 
  // Update peak usage
  const size_t used_blocks = block_count_ - free_block_count_.load(std::memory_order_relaxed);
  size_t current_peak = peak_used_blocks_.load(std::memory_order_acquire);
  while (used_blocks > current_peak) {
    if (peak_used_blocks_.compare_exchange_weak(current_peak, used_blocks, std::memory_order_release,
                                                std::memory_order_acquire)) {
      break;
    }
  }
 
  return {old_head, block_size_};
}

AllocateAndConstruct()

template<typename T , typename... Args>
requires std::constructible_from<T, Args...>

T * helios::memory::PoolAllocator::AllocateAndConstruct ( Args &&...  args )

inlinenoexcept

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 435 of file pool_allocator.hpp.

                                                                                                                {
  T* ptr = Allocate<T>();
  if (ptr != nullptr) [[likely]] {
    std::construct_at(ptr, std::forward<Args>(args)...);
  }
  return ptr;
}

BlockCount()

size_t helios::memory::PoolAllocator::BlockCount ( ) const

inlinenoexcept

Gets the block count.

Returns

Total number of blocks

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 169 of file pool_allocator.hpp.

{ return block_count_; }

BlockSize()

size_t helios::memory::PoolAllocator::BlockSize ( ) const

inlinenoexcept

Gets the block size.

Returns

Block size in bytes

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 163 of file pool_allocator.hpp.

{ return block_size_; }

Capacity()

size_t helios::memory::PoolAllocator::Capacity ( ) const

inlinenoexcept

Gets the total capacity of the pool.

Returns

Capacity in bytes

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 175 of file pool_allocator.hpp.

{ return capacity_; }

Deallocate()

void helios::memory::PoolAllocator::Deallocate ( void *  ptr )

inlinenoexcept

Deallocates a block back to the pool.

Note

Returns the block to the free list for reuse.

Warning

Triggers assertion if pointer does not belong to this pool.

Parameters

ptr	Pointer to deallocate (must have been allocated from this pool)

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 347 of file pool_allocator.hpp.

                                                        {
  if (ptr == nullptr) [[unlikely]] {
    return;
  }
 
  HELIOS_ASSERT(Owns(ptr), "Failed to deallocate memory: ptr does not belong to this pool!");
 
  // Lock-free deallocation using compare-and-swap
  void* old_head = free_list_head_atomic_.load(std::memory_order_acquire);
 
  do {
    // Set the next pointer of the block to the current head
    *reinterpret_cast<void**>(ptr) = old_head;
 
    // Try to atomically update the head pointer
  } while (!free_list_head_atomic_.compare_exchange_weak(old_head, ptr, std::memory_order_release,
                                                         std::memory_order_acquire));
 
  // Successfully deallocated - update counters
  free_block_count_.fetch_add(1, std::memory_order_relaxed);
  total_deallocations_.fetch_add(1, std::memory_order_relaxed);
}

Empty()

bool helios::memory::PoolAllocator::Empty ( ) const

inlinenoexcept

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 142 of file pool_allocator.hpp.

                                            {
    return free_block_count_.load(std::memory_order_relaxed) == block_count_;
  }

ForType()

template<typename T >

static PoolAllocator helios::memory::PoolAllocator::ForType ( size_t  block_count )

inlinestatic

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 50 of file pool_allocator.hpp.

                                                                 {
    constexpr size_t min_alignment = alignof(void*);
    constexpr size_t type_alignment = alignof(T);
    constexpr size_t alignment = type_alignment > min_alignment ? type_alignment : min_alignment;
    return {sizeof(T), block_count, alignment};
  }

FreeBlockCount()

size_t helios::memory::PoolAllocator::FreeBlockCount ( ) const

inlinenoexcept

Gets the number of free blocks.

Returns

Number of blocks available for allocation

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 181 of file pool_allocator.hpp.

{ return free_block_count_.load(std::memory_order_relaxed); }

Full()

bool helios::memory::PoolAllocator::Full ( ) const

inlinenoexcept

Checks if the allocator is full.

Returns

True if all blocks are allocated

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 141 of file pool_allocator.hpp.

{ return free_block_count_.load(std::memory_order_relaxed) == 0; }

operator=() [1/2]

PoolAllocator & helios::memory::PoolAllocator::operator= ( const PoolAllocator &  )

delete

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

operator=() [2/2]

PoolAllocator & helios::memory::PoolAllocator::operator= ( PoolAllocator &&  other )

inlinenoexcept

Definition at line 266 of file pool_allocator.hpp.

                                                                             {
  if (this == &other) [[unlikely]] {
    return *this;
  }
 
  // Free current buffer
  if (buffer_ != nullptr) {
    AlignedFree(buffer_);
  }
 
  // Move from other
  buffer_ = other.buffer_;
  free_list_head_ = other.free_list_head_;
  block_size_ = other.block_size_;
  block_count_ = other.block_count_;
  capacity_ = other.capacity_;
  alignment_ = other.alignment_;
  free_list_head_atomic_.store(other.free_list_head_atomic_.load(std::memory_order_acquire), std::memory_order_release);
  free_block_count_.store(other.free_block_count_.load(std::memory_order_acquire), std::memory_order_release);
  peak_used_blocks_.store(other.peak_used_blocks_.load(std::memory_order_acquire), std::memory_order_release);
  total_allocations_.store(other.total_allocations_.load(std::memory_order_acquire), std::memory_order_release);
  total_deallocations_.store(other.total_deallocations_.load(std::memory_order_acquire), std::memory_order_release);
 
  // Reset other
  other.buffer_ = nullptr;
  other.free_list_head_ = nullptr;
  other.block_size_ = 0;
  other.block_count_ = 0;
  other.capacity_ = 0;
  other.alignment_ = 0;
  other.free_list_head_atomic_.store(nullptr, std::memory_order_release);
  other.free_block_count_.store(0, std::memory_order_release);
  other.peak_used_blocks_.store(0, std::memory_order_release);
  other.total_allocations_.store(0, std::memory_order_release);
  other.total_deallocations_.store(0, std::memory_order_release);
 
  return *this;
}

Owns()

bool helios::memory::PoolAllocator::Owns ( const void *  ptr ) const

inlinenoexcept

Checks if a pointer belongs to this pool.

Parameters

ptr	Pointer to check

Returns

True if pointer is within pool's memory range

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 377 of file pool_allocator.hpp.

                                                              {
  if (ptr == nullptr || buffer_ == nullptr) {
    return false;
  }
 
  const auto addr = reinterpret_cast<uintptr_t>(ptr);
  const auto start = reinterpret_cast<uintptr_t>(buffer_);
  const auto end = start + capacity_;
 
  return addr >= start && addr < end;
}

Reset()

void helios::memory::PoolAllocator::Reset ( )

inlinenoexcept

Resets the pool, making all blocks available.

Rebuilds the free list, invalidating all current allocations.

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 370 of file pool_allocator.hpp.

                                          {
  InitializeFreeList();
  free_list_head_atomic_.store(free_list_head_, std::memory_order_release);
  free_block_count_.store(block_count_, std::memory_order_release);
  // Don't reset peak stats
}

Stats()

AllocatorStats helios::memory::PoolAllocator::Stats ( ) const

inlinenoexcept

Gets current allocator statistics.

Returns

AllocatorStats with current usage information

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 389 of file pool_allocator.hpp.

                                                          {
  const size_t free_blocks = free_block_count_.load(std::memory_order_relaxed);
  const size_t used_blocks = block_count_ - free_blocks;
  const size_t used_bytes = used_blocks * block_size_;
  const size_t peak_blocks = peak_used_blocks_.load(std::memory_order_relaxed);
  const size_t peak_bytes = peak_blocks * block_size_;
  const size_t total_allocs = total_allocations_.load(std::memory_order_relaxed);
  const size_t total_deallocs = total_deallocations_.load(std::memory_order_relaxed);
 
  return {
      .total_allocated = used_bytes,
      .total_freed = 0,
      .peak_usage = peak_bytes,
      .allocation_count = used_blocks,
      .total_allocations = total_allocs,
      .total_deallocations = total_deallocs,
      .alignment_waste = 0,
  };
}

UsedBlockCount()

size_t helios::memory::PoolAllocator::UsedBlockCount ( ) const

inlinenoexcept

Gets the number of used blocks.

Returns

Number of blocks currently allocated

Examples

/home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/pool_allocator.hpp.

Definition at line 187 of file pool_allocator.hpp.

                                                       {
    return block_count_ - free_block_count_.load(std::memory_order_relaxed);
  }