PSRAMAllocator< T > Class Template Reference

STL-compatible allocator that prefers PSRAM allocation with fallback. More...

#include <PSRAMAllocator.h>

Classes
struct	rebind
	Rebind allocator to different type. More...

Public Types
using	value_type = T
	The type of objects this allocator can allocate.

Public Member Functions
	PSRAMAllocator () noexcept
	Default constructor.
template<class U >
	PSRAMAllocator (const PSRAMAllocator< U > &) noexcept
	Copy constructor from different allocator type.
T *	allocate (std::size_t n)
	Allocate memory for n objects of type T.
void	deallocate (T *p, std::size_t) noexcept
	Deallocate memory previously allocated by this allocator.

Detailed Description

template<typename T = uint8_t>
class tinygpu::PSRAMAllocator< T >

STL-compatible allocator that prefers PSRAM allocation with fallback.

PSRAMAllocator is a custom C++ allocator that attempts to allocate memory in external PSRAM (using heap_caps_aligned_calloc with MALLOC_CAP_SPIRAM) and falls back to regular heap allocation if PSRAM allocation fails.

This allocator is particularly useful for ESP32 platforms with external PSRAM where large buffers (like video frames) should be stored in PSRAM to preserve internal SRAM for other uses. For small, frequently-accessed buffers that need fast access, consider using RAMAllocator instead.

Template Parameters

T	The type of objects to allocate

Note

On ESP-IDF platforms, uses heap_caps_aligned_calloc for PSRAM allocation

On Arduino platforms, the heap_caps functions are shimmed to standard malloc/free

Memory is zero-initialized (calloc behavior)

Provides proper alignment for the allocated type

Example usage:

#include "TinyGPU/Util/PSRAMAllocator.h"
 
// Use PSRAMAllocator with Vector for large buffers
std::vector<uint8_t, PSRAMAllocator<uint8_t>> largeBuffer;
largeBuffer.resize(1024 * 1024);  // Large buffer preferably in PSRAM

Member Typedef Documentation

value_type

using value_type = T

The type of objects this allocator can allocate.

Constructor & Destructor Documentation

PSRAMAllocator() [1/2]

PSRAMAllocator ( )

inlinenoexcept

Default constructor.

Constructs a PSRAMAllocator. No initialization needed.

PSRAMAllocator() [2/2]

PSRAMAllocator ( const PSRAMAllocator< U > &  )

inlinenoexcept

Copy constructor from different allocator type.

Allows construction from PSRAMAllocator of different type U. Required for STL allocator requirements.

Template Parameters

U	The type parameter of the source allocator

Parameters

other

Source allocator (unused)

Member Function Documentation

allocate()

T * allocate ( std::size_t  n )

inline

Allocate memory for n objects of type T.

Attempts to allocate memory in the following priority order:

1. PSRAM using heap_caps_aligned_calloc (if available)
2. Aligned allocation using aligned_alloc (C11)
3. Standard calloc as fallback

All allocated memory is zero-initialized.

Parameters

n	Number of objects of type T to allocate

Returns

Pointer to allocated memory

Exceptions

std::bad_alloc

if allocation fails

Note

Memory is aligned to alignof(T)

On ESP32 with PSRAM, prefers external PSRAM allocation

deallocate()

void deallocate ( T *  p, std::size_t    )

inlinenoexcept

Deallocate memory previously allocated by this allocator.

Frees memory that was allocated by allocate(). Uses heap_caps_free which works for both PSRAM and regular heap allocations.

Parameters

p	Pointer to memory to deallocate (can be nullptr)
n	Number of objects (ignored, but required by allocator interface)

Note

Safe to call with nullptr

The size parameter n is ignored as heap_caps_free doesn't need it

---

The documentation for this class was generated from the following file:

• src/TinyGPU/Util/PSRAMAllocator.h