Deki::IMemoryProvider Class Reference

The platform's memory, as the engine sees it, so the engine has no platform-specific allocation code: a microcontroller with external RAM uses its SDK's capability allocator, a part without it or a desktop uses malloc. More...

#include <deki/providers/IMemoryProvider.h>

Inherited by Deki::HostMemoryProvider.

Public Member Functions
virtual	~IMemoryProvider ()=default
virtual bool	Initialize ()=0
	Returns false on failure.
virtual void	Shutdown ()=0
virtual bool	Serves (Memory::Region region) const =0
	True when the board can place memory in region.
virtual void *	Allocate (Memory::Region region, size_t bytes, bool needsDma)=0
	Allocates bytes from region, or returns nullptr, including for a region the board does not serve; it never substitutes another region.
virtual void	Free (Memory::Region region, void *ptr)=0
	Frees a block from region.
virtual size_t	GetAvailable (Memory::Region region) const =0
	Bytes still free in region, or 0 when the platform cannot measure it.
virtual void *	AllocateRaw (size_t size)
	Allocates size bytes, or returns nullptr.
virtual void	FreeRaw (void *ptr)
	Frees a block from AllocateRaw. Override both or neither.
virtual size_t	GetRawBlockSize (void *ptr) const
	Usable size of a block from AllocateRaw, or 0 when the platform cannot say.

Detailed Description

The platform's memory, as the engine sees it, so the engine has no platform-specific allocation code: a microcontroller with external RAM uses its SDK's capability allocator, a part without it or a desktop uses malloc.

Constructor & Destructor Documentation

~IMemoryProvider()

virtual Deki::IMemoryProvider::~IMemoryProvider ( )

virtualdefault

Member Function Documentation

Initialize()

virtual bool Deki::IMemoryProvider::Initialize ( )

pure virtual

Returns false on failure.

Implemented in Deki::HostMemoryProvider.

Shutdown()

virtual void Deki::IMemoryProvider::Shutdown ( )

pure virtual

Implemented in Deki::HostMemoryProvider.

Serves()

virtual bool Deki::IMemoryProvider::Serves ( Memory::Region region ) const

pure virtual

True when the board can place memory in region.

A platform with one heap answers true for every region it can satisfy: where all memory is equally fast, "external" without PSRAM is the same place as "internal". Memory asks once at startup to report what the board has.

Implemented in Deki::HostMemoryProvider.

Allocate()

virtual void * Deki::IMemoryProvider::Allocate ( Memory::Region region, size_t bytes, bool needsDma )

pure virtual

Allocates bytes from region, or returns nullptr, including for a region the board does not serve; it never substitutes another region.

needsDma means a DMA engine must be able to read the block, in any region: a framebuffer must be reachable in internal RAM or PSRAM alike.

One entry point, not a virtual per region, because packages can define new regions (such as "rtc") without an engine release. A provider switches on region.id, a compile-time constant, and returns nullptr for any it does not know.

Implemented in Deki::HostMemoryProvider.

Free()

virtual void Deki::IMemoryProvider::Free ( Memory::Region region, void * ptr )

pure virtual

Frees a block from region.

The region comes from the allocation's own header, so callers never pass it themselves.

Implemented in Deki::HostMemoryProvider.

GetAvailable()

virtual size_t Deki::IMemoryProvider::GetAvailable ( Memory::Region region ) const

pure virtual

Bytes still free in region, or 0 when the platform cannot measure it.

It appears in the startup line and in every out-of-memory message, so a provider returning 0 should say in a comment that 0 means "unknown", not "exhausted".

Implemented in Deki::HostMemoryProvider.

AllocateRaw()

virtual void * Deki::IMemoryProvider::AllocateRaw ( size_t size )

inlinevirtual

Allocates size bytes, or returns nullptr.

Must be at least as aligned as malloc, since operator new must satisfy alignof(std::max_align_t). The default is malloc.

FreeRaw()

virtual void Deki::IMemoryProvider::FreeRaw ( void * ptr )

inlinevirtual

Frees a block from AllocateRaw. Override both or neither.

GetRawBlockSize()

virtual size_t Deki::IMemoryProvider::GetRawBlockSize ( void * ptr ) const

inlinevirtual

Usable size of a block from AllocateRaw, or 0 when the platform cannot say.

There is no header, so the heap is asked (heap_caps_get_allocated_size on ESP-IDF, _msize on Windows). Only keeps the byte total right on free; 0 costs accuracy in Memory::LogStats and nothing else.

Reimplemented in Deki::HostMemoryProvider.

---

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

• deki-engine/include/deki/providers/IMemoryProvider.h