Growable allocator adapter that automatically expands capacity. More...

#include <growable_allocator.hpp>

Public Member Functions
	GrowableAllocator (size_t initial_capacity, double growth_factor=kDefaultGrowthFactor, size_t max_allocators=0)
	Constructs a growable allocator with initial capacity.

	GrowableAllocator (const GrowableAllocator &other)
	Copy constructor.

	GrowableAllocator (GrowableAllocator &&other) noexcept
	Move constructor.

	~GrowableAllocator () noexcept=default

GrowableAllocator &	operator= (const GrowableAllocator &other)
	Copy assignment operator.

GrowableAllocator &	operator= (GrowableAllocator &&other) noexcept
	Move assignment operator.

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=0) noexcept
	Deallocates memory.

void	Reset () noexcept
	Resets all allocator instances.

bool	CanGrow () const noexcept
	Checks if the allocator can grow.

size_t	AllocatorCount () const noexcept
	Gets the number of allocator instances.

AllocatorStats	Stats () const noexcept
	Gets combined statistics for all allocator instances.

size_t	TotalCapacity () const noexcept
	Gets the total capacity across all allocator instances.

size_t	InitialCapacity () const noexcept
	Gets the initial capacity.

double	GrowthFactor () const noexcept
	Gets the growth factor.

size_t	MaxAllocators () const noexcept
	Gets the maximum number of allocators.

Static Public Attributes
static constexpr double	kDefaultGrowthFactor = 2.0

Detailed Description

template<typename Allocator>
class helios::memory::GrowableAllocator< Allocator >

Growable allocator adapter that automatically expands capacity.

Wraps another allocator and automatically creates additional allocator instances when capacity is exceeded. Manages multiple allocator instances and delegates allocations to them.

When an allocation fails due to insufficient capacity, a new allocator instance is created with a configurable growth factor applied to the initial capacity.

Supports deallocation by tracking which allocator owns each pointer.

The GrowableAllocator itself is thread-safe, using shared_mutex for optimal concurrent access. Underlying allocators are already thread-safe.

Note: Thread-safe with optimized locking. Growth occurs only when an allocation fails due to capacity constraints. Each growth creates a new allocator instance with expanded capacity. Read operations (Stats, queries) use shared locks for concurrent access. Write operations (Allocate with growth, Deallocate, Reset) use exclusive locks.

The wrapped allocator must be constructible with a single capacity argument. Compatible allocators: FrameAllocator, StackAllocator, FreeListAllocator. Not compatible with: PoolAllocator (requires additional construction parameters).

Copy operations are conditionally available based on the underlying allocator. If a custom copyable allocator is provided, GrowableAllocator will automatically support copy construction and copy assignment.

Template Parameters

Allocator The underlying allocator type to wrap

Definition at line 50 of file growable_allocator.hpp.

Constructor & Destructor Documentation

◆ GrowableAllocator() [1/3]

template<typename Allocator >

helios::memory::GrowableAllocator< Allocator >::GrowableAllocator	(	size_t	initial_capacity,
		double	growth_factor = `kDefaultGrowthFactor`,
		size_t	max_allocators = `0`
	)

inlineexplicit

Constructs a growable allocator with initial capacity.

Warning

Triggers assertion in next cases:

Initial capacity is 0.
Growth factor is less than or equal to 1.0.

Parameters

initial_capacity	Initial capacity for the first allocator instance
growth_factor	Factor to multiply capacity by when growing (default: kDefaultGrowthFactor)
max_allocators	Maximum number of allocator instances to create (0 = unlimited)

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 264 of file growable_allocator.hpp.

    : initial_capacity_(initial_capacity),
      growth_factor_(growth_factor),
      max_allocators_(max_allocators),
      next_capacity_(initial_capacity) {
  HELIOS_ASSERT(initial_capacity > 0,
                "Failed to construct GrowableAllocator: initial_capacity must be greater than 0!");
  HELIOS_ASSERT(growth_factor > 1.0,
                "Failed to construct GrowableAllocator: growth_factor must be greater than 1.0, got '{}'!",
                growth_factor);
 
  // Create the first allocator
  allocators_.reserve(max_allocators > 0 ? max_allocators : 4);
  CreateAllocator(initial_capacity_);
}

◆ GrowableAllocator() [2/3]

template<typename Allocator >
requires std::is_copy_constructible_v<Allocator>

helios::memory::GrowableAllocator< Allocator >::GrowableAllocator ( const GrowableAllocator< Allocator > & other )

inline

Copy constructor.

Note: Only available if Allocator is copy constructible. All built-in Helios allocators are non-copyable, so this will not be available for standard use cases. Provided for custom copyable allocator types.

Definition at line 282 of file growable_allocator.hpp.

    : initial_capacity_(other.initial_capacity_),
      growth_factor_(other.growth_factor_),
      max_allocators_(other.max_allocators_),
      next_capacity_(other.next_capacity_) {
  const std::shared_lock lock(other.mutex_);
  allocators_ = other.allocators_;
}

◆ GrowableAllocator() [3/3]

template<typename Allocator >
requires std::is_move_constructible_v<Allocator>

helios::memory::GrowableAllocator< Allocator >::GrowableAllocator ( GrowableAllocator< Allocator > && other )

inlinenoexcept

Move constructor.

Note: Only available if Allocator is move constructible.

Definition at line 293 of file growable_allocator.hpp.

    : allocators_(std::move(other.allocators_)),
      initial_capacity_(other.initial_capacity_),
      growth_factor_(other.growth_factor_),
      max_allocators_(other.max_allocators_),
      next_capacity_(other.next_capacity_) {
  other.initial_capacity_ = 0;
  other.growth_factor_ = kDefaultGrowthFactor;
  other.max_allocators_ = 0;
  other.next_capacity_ = 0;
}

◆ ~GrowableAllocator()

template<typename Allocator >

helios::memory::GrowableAllocator< Allocator >::~GrowableAllocator ( )

defaultnoexcept

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Member Function Documentation

◆ Allocate() [1/3]

template<typename Allocator >

template<typename T >

T * helios::memory::GrowableAllocator< Allocator >::Allocate ( )

inlinenoexcept

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 532 of file growable_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 Allocator >

template<typename T >

T * helios::memory::GrowableAllocator< Allocator >::Allocate ( size_t count )

inlinenoexcept

Definition at line 541 of file growable_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]

template<typename Allocator >

AllocationResult helios::memory::GrowableAllocator< Allocator >::Allocate	(	size_t	size,
		size_t	alignment = `kDefaultAlignment`
	)

inlinenoexcept

Allocates memory with specified size and alignment.

Attempts allocation from existing allocators. If all fail, creates a new allocator instance with expanded capacity.

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 352 of file growable_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};
  }
 
  // First, try to allocate from existing allocators with shared lock
  {
    const std::shared_lock lock(mutex_);
 
    for (auto& allocator : allocators_) {
      AllocationResult result{};
      if constexpr (requires { allocator.Allocate(size, alignment); }) {
        result = allocator.Allocate(size, alignment);
      } else if constexpr (requires { allocator.Allocate(size); }) {
        result = allocator.Allocate(size);
      }
      if (result.ptr != nullptr) {
        return result;
      }
    }
  }
 
  // All existing allocators are full, need exclusive lock for growth
  const std::scoped_lock lock(mutex_);
 
  // Try again with exclusive lock (another thread might have grown while we waited)
  for (auto& allocator : allocators_) {
    AllocationResult result{};
    if constexpr (requires { allocator.Allocate(size, alignment); }) {
      result = allocator.Allocate(size, alignment);
    } else if constexpr (requires { allocator.Allocate(size); }) {
      result = allocator.Allocate(size);
    }
    if (result.ptr != nullptr) {
      return result;
    }
  }
 
  // Still need to grow, check if we can
  if (max_allocators_ > 0 && allocators_.size() >= max_allocators_) {
    return {.ptr = nullptr, .allocated_size = 0};
  }
 
  // Calculate next capacity
  auto new_capacity = static_cast<size_t>(static_cast<double>(next_capacity_) * growth_factor_);
 
  // Ensure new capacity is at least large enough for the requested allocation
  if (new_capacity < size) {
    new_capacity = size + (size / 2);  // Add 50% extra space
  }
 
  // Create new allocator
  CreateAllocator(new_capacity);
  next_capacity_ = new_capacity;
 
  // Try to allocate from the new allocator
  auto& new_allocator = allocators_.back();
  if constexpr (requires { new_allocator.Allocate(size, alignment); }) {
    return new_allocator.Allocate(size, alignment);
  } else if constexpr (requires { new_allocator.Allocate(size); }) {
    return new_allocator.Allocate(size);
  }
  return {.ptr = nullptr, .allocated_size = 0};
}

◆ AllocateAndConstruct()

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

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

T * helios::memory::GrowableAllocator< Allocator >::AllocateAndConstruct ( Args &&... args )

inlinenoexcept

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 554 of file growable_allocator.hpp.

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

◆ AllocateAndConstructArray()

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

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

T * helios::memory::GrowableAllocator< Allocator >::AllocateAndConstructArray ( size_t count )

inlinenoexcept

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 566 of file growable_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;
}

◆ AllocatorCount()

template<typename Allocator >

size_t helios::memory::GrowableAllocator< Allocator >::AllocatorCount ( ) const

inlinenoexcept

Gets the number of allocator instances.

Returns: Number of allocator instances

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 473 of file growable_allocator.hpp.

                                                                          {
  const std::shared_lock lock(mutex_);
  return allocators_.size();
}

◆ CanGrow()

template<typename Allocator >

bool helios::memory::GrowableAllocator< Allocator >::CanGrow ( ) const

inlinenoexcept

Checks if the allocator can grow.

Returns: True if more allocator instances can be created

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 467 of file growable_allocator.hpp.

                                                                 {
  const std::shared_lock lock(mutex_);
  return max_allocators_ == 0 || allocators_.size() < max_allocators_;
}

◆ Deallocate()

template<typename Allocator >

void helios::memory::GrowableAllocator< Allocator >::Deallocate	(	void *	ptr,
		size_t	size = `0`
	)

inlinenoexcept

Deallocates memory.

Finds the allocator that owns the pointer and delegates deallocation.

Warning: Triggers assertion if pointer does not belong to any allocator instance.

Parameters

ptr	Pointer to deallocate
size	Size of allocation (for allocators that require it)

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 423 of file growable_allocator.hpp.

                                                                                    {
  if (ptr == nullptr) [[unlikely]] {
    return;
  }
 
  // Check if allocator supports deallocation at compile time
  if constexpr (
      requires { std::declval<Allocator>().Deallocate(ptr, size); } ||
      requires { std::declval<Allocator>().Deallocate(ptr); }) {
    const std::shared_lock lock(mutex_);
 
    auto* allocator = FindOwningAllocator(ptr);
    HELIOS_ASSERT(allocator != nullptr, "Failed to deallocate memory: pointer does not belong to any allocator!");
 
    // Delegate deallocation to the owning allocator
    if constexpr (requires { allocator->Deallocate(ptr, size); }) {
      allocator->Deallocate(ptr, size);
    } else if constexpr (requires { allocator->Deallocate(ptr); }) {
      allocator->Deallocate(ptr);
    }
  }
  // else: No-op for allocators that don't support individual deallocation (e.g., FrameAllocator)
}

◆ GrowthFactor()

template<typename Allocator >

double helios::memory::GrowableAllocator< Allocator >::GrowthFactor ( ) const

inlinenoexcept

Gets the growth factor.

Returns: Growth factor

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 233 of file growable_allocator.hpp.

233{ return growth_factor_; }

◆ InitialCapacity()

template<typename Allocator >

size_t helios::memory::GrowableAllocator< Allocator >::InitialCapacity ( ) const

inlinenoexcept

Gets the initial capacity.

Returns: Initial capacity in bytes

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 227 of file growable_allocator.hpp.

227{ return initial_capacity_; }

◆ MaxAllocators()

template<typename Allocator >

size_t helios::memory::GrowableAllocator< Allocator >::MaxAllocators ( ) const

inlinenoexcept

Gets the maximum number of allocators.

Returns: Maximum allocator count (0 = unlimited)

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 239 of file growable_allocator.hpp.

239{ return max_allocators_; }

◆ operator=() [1/2]

template<typename Allocator >
requires std::is_copy_assignable_v<Allocator>

auto helios::memory::GrowableAllocator< Allocator >::operator= ( const GrowableAllocator< Allocator > & other )

inline

Copy assignment operator.

Note: Only available if Allocator is copy assignable. All built-in Helios allocators are non-copyable, so this will not be available for standard use cases. Provided for custom copyable allocator types.

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 307 of file growable_allocator.hpp.

{
  if (this == &other) [[unlikely]] {
    return *this;
  }
 
  const std::scoped_lock lock(mutex_);
  const std::shared_lock other_lock(other.mutex_);
 
  allocators_ = other.allocators_;
  initial_capacity_ = other.initial_capacity_;
  growth_factor_ = other.growth_factor_;
  max_allocators_ = other.max_allocators_;
  next_capacity_ = other.next_capacity_;
 
  return *this;
}

◆ operator=() [2/2]

template<typename Allocator >
requires std::is_move_assignable_v<Allocator>

auto helios::memory::GrowableAllocator< Allocator >::operator= ( GrowableAllocator< Allocator > && other )

inlinenoexcept

Move assignment operator.

Note: Only available if Allocator is move assignable.

Definition at line 327 of file growable_allocator.hpp.

{
  if (this == &other) [[unlikely]] {
    return *this;
  }
 
  const std::scoped_lock lock(mutex_);
  const std::scoped_lock other_lock(other.mutex_);
 
  allocators_ = std::move(other.allocators_);
  initial_capacity_ = other.initial_capacity_;
  growth_factor_ = other.growth_factor_;
  max_allocators_ = other.max_allocators_;
  next_capacity_ = other.next_capacity_;
 
  other.initial_capacity_ = 0;
  other.growth_factor_ = kDefaultGrowthFactor;
  other.max_allocators_ = 0;
  other.next_capacity_ = 0;
 
  return *this;
}

◆ Reset()

template<typename Allocator >

void helios::memory::GrowableAllocator< Allocator >::Reset ( )

inlinenoexcept

Resets all allocator instances.

Resets all allocators and removes all but the first one.

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 448 of file growable_allocator.hpp.

                                                         {
  const std::scoped_lock lock(mutex_);
 
  // Reset all allocators
  for (auto& allocator : allocators_) {
    allocator.Reset();
  }
 
  // Keep only the first allocator
  if (!allocators_.empty()) {
    auto first = std::move(allocators_.front());
    allocators_.clear();
    allocators_.push_back(std::move(first));
  }
 
  next_capacity_ = initial_capacity_;
}

◆ Stats()

template<typename Allocator >

AllocatorStats helios::memory::GrowableAllocator< Allocator >::Stats ( ) const

inlinenoexcept

Gets combined statistics for all allocator instances.

Returns: AllocatorStats with combined usage information

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 479 of file growable_allocator.hpp.

                                                                         {
  const std::shared_lock lock(mutex_);
 
  AllocatorStats combined{};
 
  for (const auto& allocator : allocators_) {
    const auto stats = allocator.Stats();
    combined.total_allocated += stats.total_allocated;
    combined.total_freed += stats.total_freed;
    combined.peak_usage = std::max(combined.peak_usage, stats.peak_usage);
    combined.allocation_count += stats.allocation_count;
    combined.total_allocations += stats.total_allocations;
    combined.total_deallocations += stats.total_deallocations;
    combined.alignment_waste += stats.alignment_waste;
  }
 
  return combined;
}

◆ TotalCapacity()

template<typename Allocator >

size_t helios::memory::GrowableAllocator< Allocator >::TotalCapacity ( ) const

inlinenoexcept

Gets the total capacity across all allocator instances.

Returns: Total capacity in bytes

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 499 of file growable_allocator.hpp.

                                                                         {
  const std::shared_lock lock(mutex_);
 
  size_t total = 0;
  for (const auto& allocator : allocators_) {
    total += allocator.Capacity();
  }
  return total;
}

Member Data Documentation

◆ kDefaultGrowthFactor

template<typename Allocator >

constexpr double helios::memory::GrowableAllocator< Allocator >::kDefaultGrowthFactor = 2.0

staticconstexpr

Examples: /home/runner/work/HeliosEngine/HeliosEngine/src/core/include/helios/core/memory/growable_allocator.hpp.

Definition at line 52 of file growable_allocator.hpp.

	Helios Engine 0.1.0 A modular ECS based data-oriented C++23 game engine

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GrowableAllocator() [1/3]

◆ GrowableAllocator() [2/3]

◆ GrowableAllocator() [3/3]

◆ ~GrowableAllocator()

Member Function Documentation

◆ Allocate() [1/3]

◆ Allocate() [2/3]

◆ Allocate() [3/3]

◆ AllocateAndConstruct()

◆ AllocateAndConstructArray()

◆ AllocatorCount()

◆ CanGrow()

◆ Deallocate()

◆ GrowthFactor()

◆ InitialCapacity()

◆ MaxAllocators()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Reset()

◆ Stats()

◆ TotalCapacity()

Member Data Documentation

◆ kDefaultGrowthFactor