helios::memory::StackAllocator Class Reference

Stack/linear allocator with LIFO deallocation support. More...

#include <stack_allocator.hpp>

Public Member Functions
	StackAllocator (size_t capacity)
	Constructs a stack allocator with specified capacity.
	StackAllocator (StackAllocator &&other) noexcept
	StackAllocator (const StackAllocator &)=delete
	~StackAllocator () noexcept
StackAllocator &	operator= (const StackAllocator &)=delete
StackAllocator &	operator= (StackAllocator &&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	Deallocate (void *ptr, size_t size) noexcept
	Deallocates memory in LIFO order.
void	Reset () noexcept
	Resets the allocator, freeing all allocations.
void	RewindToMarker (size_t marker) noexcept
	Rewinds the stack to a previous marker position.
bool	Empty () const noexcept
	Checks if the allocator is empty.
bool	Full () const noexcept
	Checks if the allocator is full.
bool	Owns (const void *ptr) const noexcept
	Checks if a pointer belongs to this allocator.
AllocatorStats	Stats () const noexcept
	Gets current allocator statistics.
size_t	Marker () const noexcept
	Gets a marker for the current stack position.
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

Stack/linear allocator with LIFO deallocation support.

Allocates memory sequentially using a bump pointer, but unlike FrameAllocator, supports LIFO (stack-like) deallocations. Each allocation stores a header with the previous offset, allowing proper unwinding.

Ideal for hierarchical/scoped allocations where deallocation follows allocation order (e.g., call stacks, recursive algorithms).

Each allocation has a small header overhead for tracking.

Uses lock-free atomic operations for thread-safe allocations.

Note

Thread-safe: Multiple threads can safely call Allocate() concurrently.

Warning

Deallocations must follow LIFO order (stack discipline).

Move operations (move constructor and move assignment) are NOT thread-safe and must be externally synchronized. Do not move an allocator while other threads are accessing it.

Definition at line 39 of file stack_allocator.hpp.

Constructor & Destructor Documentation

StackAllocator() [1/3]

helios::memory::StackAllocator::StackAllocator ( size_t  capacity )

inlineexplicit

Constructs a stack 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/stack_allocator.hpp.

Definition at line 233 of file stack_allocator.hpp.

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

StackAllocator() [2/3]

helios::memory::StackAllocator::StackAllocator ( StackAllocator &&  other )

inlinenoexcept

Definition at line 247 of file stack_allocator.hpp.

    : buffer_(other.buffer_),
      capacity_{other.capacity_.load(std::memory_order_relaxed)},
      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)),
      total_allocations_(other.total_allocations_.load(std::memory_order_acquire)),
      total_deallocations_(other.total_deallocations_.load(std::memory_order_acquire)),
      alignment_waste_(other.alignment_waste_.load(std::memory_order_acquire)) {
  other.buffer_ = nullptr;
  other.capacity_.store(0, std::memory_order_relaxed);
  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.total_allocations_.store(0, std::memory_order_release);
  other.total_deallocations_.store(0, std::memory_order_release);
  other.alignment_waste_.store(0, std::memory_order_release);
}

StackAllocator() [3/3]

helios::memory::StackAllocator::StackAllocator ( const StackAllocator &  )

delete

~StackAllocator()

helios::memory::StackAllocator::~StackAllocator ( )

inlinenoexcept

Examples

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

Definition at line 241 of file stack_allocator.hpp.

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

Member Function Documentation

Allocate() [1/3]

template<typename T >

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

inlinenoexcept

Examples

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

Definition at line 445 of file stack_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::StackAllocator::Allocate ( size_t  count )

inlinenoexcept

Definition at line 453 of file stack_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::StackAllocator::Allocate ( size_t  size, size_t  alignment = kDefaultAlignment  )

inlinenoexcept

Allocates memory with specified size and alignment.

Stores allocation header for LIFO deallocation support

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 300 of file stack_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};
  }
 
  // Lock-free allocation using compare-and-swap
  size_t current_offset = offset_.load(std::memory_order_acquire);
  size_t new_offset = 0;
  size_t header_padding = 0;
  uint8_t* current_ptr = nullptr;
 
  do {
    // Calculate space needed for header + alignment
    current_ptr = static_cast<uint8_t*>(buffer_) + current_offset;
    header_padding = CalculatePaddingWithHeader(current_ptr, alignment, sizeof(AllocationHeader));
    const size_t required_space = header_padding + size;
 
    // Check if we have enough space
    if (current_offset + required_space > capacity_.load(std::memory_order_relaxed)) {
      return {.ptr = nullptr, .allocated_size = 0};
    }
 
    new_offset = current_offset + required_space;
 
    // Try to atomically update offset
  } while (
      !offset_.compare_exchange_weak(current_offset, new_offset, std::memory_order_release, std::memory_order_acquire));
 
  // Successfully reserved space - now write the header
  // This is safe because we own the range [current_offset, new_offset)
  auto* header_ptr = current_ptr + header_padding - sizeof(AllocationHeader);
  auto* header = reinterpret_cast<AllocationHeader*>(header_ptr);
  header->previous_offset = current_offset;
  header->padding = header_padding;
 
  // Update stats
  allocation_count_.fetch_add(1, std::memory_order_relaxed);
  total_allocations_.fetch_add(1, std::memory_order_relaxed);
  alignment_waste_.fetch_add(header_padding - sizeof(AllocationHeader), 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;
    }
  }
 
  // Calculate aligned data pointer
  uint8_t* data_ptr = current_ptr + header_padding;
  return {data_ptr, size};
}

AllocateAndConstruct()

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

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

inlinenoexcept

Examples

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

Definition at line 465 of file stack_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::StackAllocator::AllocateAndConstructArray ( size_t  count )

inlinenoexcept

Examples

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

Definition at line 475 of file stack_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::StackAllocator::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/stack_allocator.hpp.

Definition at line 199 of file stack_allocator.hpp.

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

CurrentOffset()

size_t helios::memory::StackAllocator::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/stack_allocator.hpp.

Definition at line 205 of file stack_allocator.hpp.

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

Deallocate()

void helios::memory::StackAllocator::Deallocate ( void *  ptr, size_t  size  )

inlinenoexcept

Deallocates memory in LIFO order.

Warning

Triggers assertion in next cases:

• Pointer does not belong to this allocator.
• Deallocation violates LIFO order.

Parameters

ptr	Pointer to deallocate (must be the most recent allocation)
size	Size of allocation (used for validation)

Examples

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

Definition at line 359 of file stack_allocator.hpp.

                                                                                       {
  if (ptr == nullptr) [[unlikely]] {
    return;
  }
 
  HELIOS_ASSERT(Owns(ptr), "Failed to deallocate memory: ptr does not belong to this allocator!");
 
  // Get the header stored before the allocation
  auto* header = reinterpret_cast<AllocationHeader*>(static_cast<uint8_t*>(ptr) - sizeof(AllocationHeader));
 
#ifdef HELIOS_DEBUG_MODE
  {
    // Verify this is the most recent allocation (LIFO check)
    const size_t current_offset = offset_.load(std::memory_order_acquire);
    HELIOS_ASSERT(static_cast<uint8_t*>(ptr) + size <= static_cast<uint8_t*>(buffer_) + current_offset,
                  "Failed to deallocate memory:  Deallocation violates LIFO order!");
  }
#endif
 
  // Rewind to previous offset
  // Note: LIFO deallocations are expected to be single-threaded per stack or externally synchronized
  offset_.store(header->previous_offset, std::memory_order_release);
 
  // Update stats
  allocation_count_.fetch_sub(1, std::memory_order_relaxed);
  total_deallocations_.fetch_add(1, std::memory_order_relaxed);
}

Empty()

bool helios::memory::StackAllocator::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/stack_allocator.hpp.

Definition at line 167 of file stack_allocator.hpp.

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

FreeSpace()

size_t helios::memory::StackAllocator::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/stack_allocator.hpp.

Definition at line 438 of file stack_allocator.hpp.

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

Full()

bool helios::memory::StackAllocator::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/allocator_resources.hpp, and /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/stack_allocator.hpp.

Definition at line 173 of file stack_allocator.hpp.

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

Marker()

size_t helios::memory::StackAllocator::Marker ( ) const

inlinenoexcept

Gets a marker for the current stack position.

Note

Can be used with RewindToMarker for bulk deallocations.

Returns

Current offset as a marker

Examples

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

Definition at line 193 of file stack_allocator.hpp.

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

operator=() [1/2]

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

delete

Examples

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

operator=() [2/2]

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

inlinenoexcept

Definition at line 266 of file stack_allocator.hpp.

                                                                                {
  if (this == &other) [[unlikely]] {
    return *this;
  }
 
  // Free current buffer
  if (buffer_ != nullptr) {
    AlignedFree(buffer_);
  }
 
  // Move from other
  buffer_ = other.buffer_;
  capacity_.store(other.capacity_.load(std::memory_order_relaxed), std::memory_order_relaxed);
 
  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);
  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);
  alignment_waste_.store(other.alignment_waste_.load(std::memory_order_acquire), std::memory_order_release);
 
  // Reset other
  other.buffer_ = nullptr;
  other.capacity_.store(0, std::memory_order_relaxed);
  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.total_allocations_.store(0, std::memory_order_release);
  other.total_deallocations_.store(0, std::memory_order_release);
  other.alignment_waste_.store(0, std::memory_order_release);
 
  return *this;
}

Owns()

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

inlinenoexcept

Checks if a pointer belongs to this allocator.

Parameters

ptr	Pointer to check

Returns

True if pointer is within allocator's memory range

Examples

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

Definition at line 407 of file stack_allocator.hpp.

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

Reset()

void helios::memory::StackAllocator::Reset ( )

inlinenoexcept

Resets the allocator, freeing all allocations.

Resets the internal offset to 0, effectively freeing all memory.

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

Definition at line 387 of file stack_allocator.hpp.

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

RewindToMarker()

void helios::memory::StackAllocator::RewindToMarker ( size_t  marker )

inlinenoexcept

Rewinds the stack to a previous marker position.

Invalidates all allocations made after the marker

Warning

Triggers assertion in next cases:

• Marker is ahead of current offset.
• Marker exceeds capacity.

Parameters

marker

Previously obtained marker from Marker()

Examples

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

Definition at line 393 of file stack_allocator.hpp.

                                                                 {
  [[maybe_unused]] const size_t current_offset = offset_.load(std::memory_order_acquire);
  HELIOS_ASSERT(marker <= current_offset, "Failed to rewind to marker: marker '{}' is ahead of current offset '{}'!",
                marker, current_offset);
 
  const size_t capacity = capacity_.load(std::memory_order_relaxed);
  HELIOS_ASSERT(marker <= capacity, "Failed to rewind to marker: marker '{}' exceeds capacity '{}'!", marker, capacity);
 
  offset_.store(marker, std::memory_order_release);
 
  // Note: allocation_count_ becomes inaccurate after rewind, but that's acceptable
  // since we're doing bulk deallocation
}

Stats()

AllocatorStats helios::memory::StackAllocator::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/stack_allocator.hpp.

Definition at line 419 of file stack_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 total_allocs = total_allocations_.load(std::memory_order_relaxed);
  const size_t total_deallocs = total_deallocations_.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 = total_allocs,
      .total_deallocations = total_deallocs,
      .alignment_waste = waste,
  };
}