helios::memory::FrameAllocator Class Reference

Linear allocator that clears every frame. More...

#include <frame_allocator.hpp>

Public Member Functions
	FrameAllocator (size_t capacity)
	Constructs a frame allocator with specified capacity.
	FrameAllocator (const FrameAllocator &)=delete
	FrameAllocator (FrameAllocator &&other) noexcept
	~FrameAllocator () noexcept
FrameAllocator &	operator= (const FrameAllocator &)=delete
FrameAllocator &	operator= (FrameAllocator &&other) noexcept
AllocationResult	Allocate (size_t size, size_t alignment=kDefaultAlignment) noexcept
	Allocates memory with specified size and alignment.
template<typename T >
T *	Allocate () noexcept
template<typename T >
T *	Allocate (size_t count) noexcept
template<typename T , typename... Args> requires std::constructible_from<T, Args...>
T *	AllocateAndConstruct (Args &&... args) noexcept(std::is_nothrow_constructible_v< T, Args... >)
template<typename T > requires std::default_initializable<T>
T *	AllocateAndConstructArray (size_t count) noexcept(std::is_nothrow_default_constructible_v< T >)
void	Reset () noexcept
	Resets the allocator, freeing all allocations.
bool	Empty () const noexcept
	Checks if the allocator is empty.
bool	Full () const noexcept
	Checks if the allocator is full.
AllocatorStats	Stats () const noexcept
	Gets current allocator statistics.
size_t	Capacity () const noexcept
	Gets the total capacity of the allocator.
size_t	CurrentOffset () const noexcept
	Gets the current offset (amount of memory used).
size_t	FreeSpace () const noexcept
	Gets the amount of free space remaining.

Detailed Description

Linear allocator that clears every frame.

Fast bump-pointer allocator for per-frame temporary allocations. Extremely efficient for short-lived allocations that don't need individual deallocation. All memory is freed at once when Reset() is called (typically at frame end).

Uses atomic operations for allocation offset tracking.

Ideal for temporary data that lives for a single frame.

Note

Thread-safe. Deallocation is a no-op - memory is only freed on Reset().

Warning

Data allocated with this allocator is only valid until Reset() is called. All pointers and references to allocated memory become invalid after Reset(). Do not store frame-allocated data in persistent storage (components, resources, etc.).

Definition at line 35 of file frame_allocator.hpp.

Constructor & Destructor Documentation

FrameAllocator() [1/3]

helios::memory::FrameAllocator::FrameAllocator ( size_t  capacity )

inlineexplicit

Constructs a frame allocator with specified capacity.

Warning

Triggers assertion if capacity is 0.

Parameters

capacity

Total size of the memory buffer in bytes

Examples

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

Definition at line 186 of file frame_allocator.hpp.

                                                     : capacity_(capacity) {
  HELIOS_ASSERT(capacity > 0, "Failed to construct FrameAllocator: capacity must be greater than 0!");
 
  // Allocate aligned buffer
  buffer_ = AlignedAlloc(kDefaultAlignment, capacity_);
  HELIOS_VERIFY(buffer_ != nullptr, "Failed to construct FrameAllocator: Allocation of buffer failed!");
}

FrameAllocator() [2/3]

helios::memory::FrameAllocator::FrameAllocator ( const FrameAllocator &  )

delete

FrameAllocator() [3/3]

helios::memory::FrameAllocator::FrameAllocator ( FrameAllocator &&  other )

inlinenoexcept

Definition at line 194 of file frame_allocator.hpp.

    : buffer_(other.buffer_),
      capacity_(other.capacity_),
      offset_(other.offset_.load(std::memory_order_acquire)),
      peak_offset_(other.peak_offset_.load(std::memory_order_acquire)),
      allocation_count_(other.allocation_count_.load(std::memory_order_acquire)),
      alignment_waste_(other.alignment_waste_.load(std::memory_order_acquire)) {
  other.buffer_ = nullptr;
  other.capacity_ = 0;
  other.offset_.store(0, std::memory_order_release);
  other.peak_offset_.store(0, std::memory_order_release);
  other.allocation_count_.store(0, std::memory_order_release);
  other.alignment_waste_.store(0, std::memory_order_release);
}

~FrameAllocator()

helios::memory::FrameAllocator::~FrameAllocator ( )

inlinenoexcept

Examples

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

Definition at line 209 of file frame_allocator.hpp.

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

Member Function Documentation

Allocate() [1/3]

template<typename T >

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

inlinenoexcept

Examples

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

Definition at line 323 of file frame_allocator.hpp.

                                            {
  constexpr size_t size = sizeof(T);
  constexpr size_t alignment = std::max(alignof(T), kMinAlignment);
  auto result = Allocate(size, alignment);
  return static_cast<T*>(result.ptr);
}

Allocate() [2/3]

template<typename T >

T * helios::memory::FrameAllocator::Allocate ( size_t  count )

inlinenoexcept

Definition at line 331 of file frame_allocator.hpp.

                                                        {
  if (count == 0) [[unlikely]] {
    return nullptr;
  }
  constexpr size_t alignment = std::max(alignof(T), kMinAlignment);
  const size_t size = sizeof(T) * count;
  auto result = Allocate(size, alignment);
  return static_cast<T*>(result.ptr);
}

Allocate() [3/3]

AllocationResult helios::memory::FrameAllocator::Allocate ( size_t  size, size_t  alignment = kDefaultAlignment  )

inlinenoexcept

Allocates memory with specified size and alignment.

Warning

Triggers assertion in next cases:

• Alignment is not a power of 2.
• Alignment is less than kMinAlignment.

Parameters

size	Number of bytes to allocate
alignment	Alignment requirement (must be power of 2)

Returns

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

Definition at line 244 of file frame_allocator.hpp.

                                                                                       {
  HELIOS_ASSERT(IsPowerOfTwo(alignment), "Failed to allocate memory: alignment must be power of 2, got '{}'!",
                alignment);
  HELIOS_ASSERT(alignment >= kMinAlignment, "Failed to allocate memory: alignment must be at least '{}', got '{}'!",
                kMinAlignment, alignment);
 
  if (size == 0) [[unlikely]] {
    return {.ptr = nullptr, .allocated_size = 0};
  }
 
  // Atomically allocate using compare-and-swap
  size_t current_offset = offset_.load(std::memory_order_acquire);
  size_t aligned_offset = 0;
  size_t new_offset = 0;
  size_t padding = 0;
 
  do {
    // Calculate aligned offset
    auto* current_ptr = static_cast<uint8_t*>(buffer_) + current_offset;
    padding = CalculatePadding(current_ptr, alignment);
    aligned_offset = current_offset + padding;
 
    // Check if we have enough space
    if (aligned_offset + size > capacity_) {
      return {.ptr = nullptr, .allocated_size = 0};
    }
 
    new_offset = aligned_offset + size;
 
    // Try to atomically update offset
  } while (
      !offset_.compare_exchange_weak(current_offset, new_offset, std::memory_order_release, std::memory_order_acquire));
 
  // Update stats (these don't need to be perfectly accurate)
  allocation_count_.fetch_add(1, std::memory_order_relaxed);
  alignment_waste_.fetch_add(padding, std::memory_order_relaxed);
 
  // Update peak offset
  size_t current_peak = peak_offset_.load(std::memory_order_acquire);
  while (new_offset > current_peak) {
    if (peak_offset_.compare_exchange_weak(current_peak, new_offset, std::memory_order_release,
                                           std::memory_order_acquire)) {
      break;
    }
  }
 
  void* result = static_cast<uint8_t*>(buffer_) + aligned_offset;
  return {.ptr = result, .allocated_size = size};
}

AllocateAndConstruct()

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

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

inlinenoexcept

Examples

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

Definition at line 343 of file frame_allocator.hpp.

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

AllocateAndConstructArray()

template<typename T >
requires std::default_initializable<T>

T * helios::memory::FrameAllocator::AllocateAndConstructArray ( size_t  count )

inlinenoexcept

Examples

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

Definition at line 353 of file frame_allocator.hpp.

                                                                                                                   {
  T* ptr = Allocate<T>(count);
  if (ptr != nullptr) [[likely]] {
    for (size_t i = 0; i < count; ++i) {
      std::construct_at(ptr + i);
    }
  }
  return ptr;
}

Capacity()

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

inlinenoexcept

Gets the total capacity of the allocator.

Returns

Capacity 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/frame_allocator.hpp.

Definition at line 163 of file frame_allocator.hpp.

{ return capacity_; }

CurrentOffset()

size_t helios::memory::FrameAllocator::CurrentOffset ( ) const

inlinenoexcept

Gets the current offset (amount of memory used).

Returns

Current offset in bytes

Examples

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

Definition at line 169 of file frame_allocator.hpp.

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

Empty()

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

inlinenoexcept

Checks if the allocator is empty.

Returns

True if no allocations have been made since last reset

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/frame_allocator.hpp.

Definition at line 145 of file frame_allocator.hpp.

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

FreeSpace()

size_t helios::memory::FrameAllocator::FreeSpace ( ) const

inlinenoexcept

Gets the amount of free space remaining.

Returns

Free space in bytes

Examples

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

Definition at line 317 of file frame_allocator.hpp.

                                                       {
  const size_t current = offset_.load(std::memory_order_relaxed);
  return current < capacity_ ? capacity_ - current : 0;
}

Full()

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

inlinenoexcept

Checks if the allocator is full.

Returns

True if no more allocations can be made without reset

Examples

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

Definition at line 151 of file frame_allocator.hpp.

{ return offset_.load(std::memory_order_relaxed) >= capacity_; }

operator=() [1/2]

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

delete

Examples

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

operator=() [2/2]

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

inlinenoexcept

Definition at line 215 of file frame_allocator.hpp.

                                                                                {
  if (this == &other) [[unlikely]] {
    return *this;
  }
 
  // Free current buffer
  if (buffer_ != nullptr) {
    AlignedFree(buffer_);
  }
 
  // Move from other
  buffer_ = other.buffer_;
  capacity_ = other.capacity_;
  offset_.store(other.offset_.load(std::memory_order_acquire), std::memory_order_release);
  peak_offset_.store(other.peak_offset_.load(std::memory_order_acquire), std::memory_order_release);
  allocation_count_.store(other.allocation_count_.load(std::memory_order_acquire), std::memory_order_release);
  alignment_waste_.store(other.alignment_waste_.load(std::memory_order_acquire), std::memory_order_release);
 
  // Reset other
  other.buffer_ = nullptr;
  other.capacity_ = 0;
  other.offset_.store(0, std::memory_order_release);
  other.peak_offset_.store(0, std::memory_order_release);
  other.allocation_count_.store(0, std::memory_order_release);
  other.alignment_waste_.store(0, std::memory_order_release);
 
  return *this;
}

Reset()

void helios::memory::FrameAllocator::Reset ( )

inlinenoexcept

Resets the allocator, freeing all allocations.

Resets the internal offset to 0, effectively freeing all memory. Does not actually free or zero the underlying buffer.

Warning

All pointers obtained from this allocator become invalid after this call. Do not store references or pointers to frame-allocated data beyond the current frame.

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/frame_allocator.hpp.

Definition at line 294 of file frame_allocator.hpp.

                                           {
  offset_.store(0, std::memory_order_release);
  alignment_waste_.store(0, std::memory_order_release);
  allocation_count_.store(0, std::memory_order_release);
}

Stats()

AllocatorStats helios::memory::FrameAllocator::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/frame_allocator.hpp.

Definition at line 300 of file frame_allocator.hpp.

                                                           {
  const size_t current_offset = offset_.load(std::memory_order_relaxed);
  const size_t peak = peak_offset_.load(std::memory_order_relaxed);
  const size_t alloc_count = allocation_count_.load(std::memory_order_relaxed);
  const size_t waste = alignment_waste_.load(std::memory_order_relaxed);
 
  return {
      .total_allocated = current_offset,
      .total_freed = 0,
      .peak_usage = peak,
      .allocation_count = alloc_count,
      .total_allocations = alloc_count,
      .total_deallocations = 0,
      .alignment_waste = waste,
  };
}