Memory Namespace Reference

Detailed Description

Allocates memory using the TLSF method (http://www.gii.upv.es/tlsf/files/ecrts04_tlsf.pdf), with extended handling of padding to better suit GPUs.

Doesn't manage memory itself but is meant to be used with a memory allocation of maxSize. Fast O(1) insertion and deletion and with minimal fragmentation.

Copyright

(C) 2023 Individual contributors, see AUTHORS file

Classes
class	ArenaAllocator
	Allocates memory in chunks. More...
class	PoolArrayAllocator
	Allocates small memory blocks from an array of fixed-size memory pools. More...
struct	RangeAllocation
class	RangeAllocator
struct	RingAlloc
class	RingAllocator
	Allocates memory up-front, and then allows other systems to grab regions. More...
struct	TotalMemoryStatus
	Get the system's total current memory, this does not only include Nebula's memory allocations but the memory usage of the entire system. More...

Enumerations
enum	HeapType {   DefaultHeap = 0 , ObjectHeap , ObjectArrayHeap , ResourceHeap ,   ScratchHeap , StringDataHeap , StreamDataHeap , PhysicsHeap ,   AppHeap , NumHeapTypes , InvalidHeapType , DefaultHeap = 0 ,   ObjectHeap , ObjectArrayHeap , ResourceHeap , ScratchHeap ,   StringDataHeap , StreamDataHeap , PhysicsHeap , AppHeap ,   NetworkHeap , ScriptingHeap , NumHeapTypes , InvalidHeapType ,   DefaultHeap = 0 , ObjectHeap , ObjectArrayHeap , ResourceHeap ,   ScratchHeap , StringDataHeap , StreamDataHeap , PhysicsHeap ,   AppHeap , NetworkHeap , ScriptingHeap , NumHeapTypes ,   InvalidHeapType }
	Heap types are defined here. More...
enum	HeapType {   DefaultHeap = 0 , ObjectHeap , ObjectArrayHeap , ResourceHeap ,   ScratchHeap , StringDataHeap , StreamDataHeap , PhysicsHeap ,   AppHeap , NumHeapTypes , InvalidHeapType , DefaultHeap = 0 ,   ObjectHeap , ObjectArrayHeap , ResourceHeap , ScratchHeap ,   StringDataHeap , StreamDataHeap , PhysicsHeap , AppHeap ,   NetworkHeap , ScriptingHeap , NumHeapTypes , InvalidHeapType ,   DefaultHeap = 0 , ObjectHeap , ObjectArrayHeap , ResourceHeap ,   ScratchHeap , StringDataHeap , StreamDataHeap , PhysicsHeap ,   AppHeap , NetworkHeap , ScriptingHeap , NumHeapTypes ,   InvalidHeapType }
	Heap types are defined here. More...
enum	HeapType {   DefaultHeap = 0 , ObjectHeap , ObjectArrayHeap , ResourceHeap ,   ScratchHeap , StringDataHeap , StreamDataHeap , PhysicsHeap ,   AppHeap , NumHeapTypes , InvalidHeapType , DefaultHeap = 0 ,   ObjectHeap , ObjectArrayHeap , ResourceHeap , ScratchHeap ,   StringDataHeap , StreamDataHeap , PhysicsHeap , AppHeap ,   NetworkHeap , ScriptingHeap , NumHeapTypes , InvalidHeapType ,   DefaultHeap = 0 , ObjectHeap , ObjectArrayHeap , ResourceHeap ,   ScratchHeap , StringDataHeap , StreamDataHeap , PhysicsHeap ,   AppHeap , NetworkHeap , ScriptingHeap , NumHeapTypes ,   InvalidHeapType }
	Heap types are defined here. More...

Functions
void *	Alloc (HeapType heapType, size_t size, size_t alignment)
	Allocate a block of memory from one of the global heaps.
void *	Realloc (HeapType heapType, void *ptr, size_t size)
	Re-Allocate a block of memory from one of the global heaps.
void	Free (HeapType heapType, void *ptr)
	Free a block of memory.
char *	DuplicateCString (const char *from)
	Duplicate a 0-terminated string, this method should no longer be used!
bool	IsOverlapping (const unsigned char *srcPtr, size_t srcSize, const unsigned char *dstPtr, size_t dstSize)
	Test if 2 areas of memory areas are overlapping.
TotalMemoryStatus	GetTotalMemoryStatus ()
	Get the system's total memory status.
void	Copy (const void *from, void *to, size_t numBytes)
	Copy a chunk of memory (note the argument order is different from memcpy()!!!)
void	Clear (void *ptr, size_t numBytes)
	Overwrite a chunk of memory with 0's.
void	Fill (void *ptr, size_t numBytes, unsigned char value)
	Fill memory with a specific byte.
void	SetupHeaps ()
	Setup the global heaps.
const char *	GetHeapTypeName (HeapType heapType)
	Returns a human readable name for a heap type.
__forceinline void *	AllocVirtual (size_t size)
	allocate a range of virtual memory space
__forceinline void	DecommitVirtual (void *ptr, size_t size)
	decommit virtual memory
__forceinline void	CommitVirtual (void *ptr, size_t size)
	commit virtual memory
__forceinline void	FreeVirtual (void *ptr, size_t size)
	free virtual memory
__forceinline void	Move (const void *from, void *to, size_t numBytes)
	Move a chunk of memory, can handle overlapping regions.
template<typename T >
__forceinline void	MoveElements (const T *from, T *to, size_t numElements)
	Move a chunk of memory, can handle overlapping regions.
template<typename T >
__forceinline void	CopyElements (const T *from, T *to, size_t numElements)
	Copy a chunk of memory (note the argument order is different from memcpy()!!!)
__forceinline void	CopyToGraphicsMemory (const void *from, void *to, size_t numBytes)
	Copy data from a system memory buffer to graphics resource memory.
uint	BucketFromSize (uint size)
	Get bucket from index.
uint	BinFromSize (uint size, uint bucket)
	Get bin from index.
void	DumpTotalMemoryStatus ()
	Dump detail memory status information.
__forceinline unsigned char *	__HeapAlignPointerAndWritePadding16 (unsigned char *ptr)
	Global PoolArrayAllocator objects, these are all setup in a central place in the Memory::SetupHeaps() function!
__forceinline unsigned char *	__HeapUnalignPointer16 (unsigned char *ptr)
	Helper function for Heap16 functions: "un-aligns" pointer through the padding mask stored in the byte before the pointer.
__forceinline LPVOID	__HeapAlloc16 (HANDLE hHeap, DWORD dwFlags, SIZE_T dwBytes)
	HeapAlloc replacement which always returns 16-byte aligned addresses.
__forceinline LPVOID	__HeapReAlloc16 (HANDLE hHeap, DWORD dwFlags, LPVOID lpMem, SIZE_T dwBytes)
	HeapReAlloc replacement for 16-byte alignment.
__forceinline BOOL	__HeapFree16 (HANDLE hHeap, DWORD dwFlags, LPVOID lpMem)
	HeapFree replacement which always returns 16-byte aligned addresses.
__forceinline SIZE_T	__HeapSize16 (HANDLE hHeap, DWORD dwFlags, LPCVOID lpMem)
	HeapSize replacement function.

Variables
int volatile	TotalAllocCount = 0
int volatile	TotalAllocSize = 0
int volatile	HeapTypeAllocCount [NumHeapTypes] = { 0 }
int volatile	HeapTypeAllocSize [NumHeapTypes] = { 0 }
bool volatile	MemoryLoggingEnabled = false
unsigned int volatile	MemoryLoggingThreshold = 0
HeapType volatile	MemoryLoogingHeapType
malloc_zone_t *	Heaps [NumHeapTypes] = { NULL }
	Heap pointers are defined here.
void *volatile	PosixProcessHeap = 0
static constexpr uint	NUM_BUCKETS = 0x20
static constexpr uint	NUM_BINS_PER_BUCKET = 0x10
HANDLE volatile	Win32ProcessHeap = 0
HeapType volatile	MemoryLoggingHeapType = InvalidHeapType

Enumeration Type Documentation

HeapType [1/3]

enum Memory::HeapType

Heap types are defined here.

The main purpose for the different heap types is to decrease memory fragmentation and to improve cache usage by grouping similar data together. Platform ports may define platform-specific heap types, as long as only platform specific code uses those new heap types.

Enumerator
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NumHeapTypes
InvalidHeapType
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NetworkHeap
ScriptingHeap
NumHeapTypes
InvalidHeapType
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NetworkHeap
ScriptingHeap
NumHeapTypes
InvalidHeapType

HeapType [2/3]

enum Memory::HeapType

Heap types are defined here.

The main purpose for the different heap types is to decrease memory fragmentation and to improve cache usage by grouping similar data together. Platform ports may define platform-specific heap types, as long as only platform specific code uses those new heap types.

Enumerator
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NumHeapTypes
InvalidHeapType
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NetworkHeap
ScriptingHeap
NumHeapTypes
InvalidHeapType
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NetworkHeap
ScriptingHeap
NumHeapTypes
InvalidHeapType

HeapType [3/3]

enum Memory::HeapType

Heap types are defined here.

The main purpose for the different heap types is to decrease memory fragmentation and to improve cache usage by grouping similar data together. Platform ports may define platform-specific heap types, as long as only platform specific code uses those new heap types.

Enumerator
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NumHeapTypes
InvalidHeapType
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NetworkHeap
ScriptingHeap
NumHeapTypes
InvalidHeapType
DefaultHeap
ObjectHeap
ObjectArrayHeap
ResourceHeap
ScratchHeap
StringDataHeap
StreamDataHeap
PhysicsHeap
AppHeap
NetworkHeap
ScriptingHeap
NumHeapTypes
InvalidHeapType

Function Documentation

__HeapAlignPointerAndWritePadding16()

__forceinline unsigned char * Memory::__HeapAlignPointerAndWritePadding16

(

unsigned char *

ptr

)

Global PoolArrayAllocator objects, these are all setup in a central place in the Memory::SetupHeaps() function!

Helper function for Heap16 functions: aligns pointer to 16 byte and writes padding mask to byte before returned pointer.

__HeapAlloc16()

__forceinline LPVOID Memory::__HeapAlloc16	(	HANDLE	hHeap,
		DWORD	dwFlags,
		SIZE_T	dwBytes )

HeapAlloc replacement which always returns 16-byte aligned addresses.

NOTE: only works for 32 bit pointers!

__HeapFree16()

__forceinline BOOL Memory::__HeapFree16	(	HANDLE	hHeap,
		DWORD	dwFlags,
		LPVOID	lpMem )

HeapFree replacement which always returns 16-byte aligned addresses.

NOTE: only works for 32 bit pointers!

__HeapReAlloc16()

__forceinline LPVOID Memory::__HeapReAlloc16	(	HANDLE	hHeap,
		DWORD	dwFlags,
		LPVOID	lpMem,
		SIZE_T	dwBytes )

HeapReAlloc replacement for 16-byte alignment.

NOTE: only works for 32 bit pointers!

__HeapSize16()

__forceinline SIZE_T Memory::__HeapSize16	(	HANDLE	hHeap,
		DWORD	dwFlags,
		LPCVOID	lpMem )

HeapSize replacement function.

__HeapUnalignPointer16()

__forceinline unsigned char * Memory::__HeapUnalignPointer16

(

unsigned char *

ptr

)

Helper function for Heap16 functions: "un-aligns" pointer through the padding mask stored in the byte before the pointer.

Alloc()

void * Memory::Alloc	(	HeapType	heapType,
		size_t	size,
		size_t	alignment = 16 )

Allocate a block of memory from one of the global heaps.

Allocate a block of memory from the process heap.

Global memory functions.

allocate a chunk of memory

AllocVirtual()

void * Memory::AllocVirtual

(

size_t

size

)

allocate a range of virtual memory space

BinFromSize()

uint Memory::BinFromSize ( uint size, uint bucket )

inline

Get bin from index.

BucketFromSize()

uint Memory::BucketFromSize ( uint size )

inline

Get bucket from index.

Clear()

__forceinline void Memory::Clear	(	void *	ptr,
		size_t	numBytes )

Overwrite a chunk of memory with 0's.

overwrite a chunk of memory with zero

CommitVirtual()

void Memory::CommitVirtual	(	void *	ptr,
		size_t	size )

commit virtual memory

Copy()

__forceinline void Memory::Copy	(	const void *	from,
		void *	to,
		size_t	numBytes )

Copy a chunk of memory (note the argument order is different from memcpy()!!!)

copy a chunk of memory

CopyElements()

template<typename T >

__forceinline void Memory::CopyElements	(	const T *	from,
		T *	to,
		size_t	numElements )

Copy a chunk of memory (note the argument order is different from memcpy()!!!)

CopyToGraphicsMemory()

__forceinline void Memory::CopyToGraphicsMemory	(	const void *	from,
		void *	to,
		size_t	numBytes )

Copy data from a system memory buffer to graphics resource memory.

Some platforms may need special handling of this case.

DecommitVirtual()

void Memory::DecommitVirtual	(	void *	ptr,
		size_t	size )

decommit virtual memory

DumpTotalMemoryStatus()

void Memory::DumpTotalMemoryStatus

(

)

Dump detail memory status information.

DuplicateCString()

char * Memory::DuplicateCString

(

const char *

from

)

Duplicate a 0-terminated string, this method should no longer be used!

duplicate a C-string

Duplicate a 0-terminated string.

duplicate a C-string (obsolete)

The memory will be allocated from the StringHeap (important when freeing the memory!)

The memory will be allocated from the StringDataHeap (important when freeing the memory!)

Fill()

__forceinline void Memory::Fill	(	void *	ptr,
		size_t	numBytes,
		unsigned char	value )

Fill memory with a specific byte.

fill memory with a specific byte

Free()

void Memory::Free	(	HeapType	heapType,
		void *	ptr )

Free a block of memory.

Free a chunk of memory from the process heap.

free a chunk of memory

FreeVirtual()

void Memory::FreeVirtual	(	void *	ptr,
		size_t	size )

free virtual memory

GetHeapTypeName()

const char * Memory::GetHeapTypeName

(

HeapType

heapType

)

Returns a human readable name for a heap type.

GetTotalMemoryStatus()

TotalMemoryStatus Memory::GetTotalMemoryStatus ( )

inline

Get the system's total memory status.

IsOverlapping()

bool Memory::IsOverlapping ( const unsigned char * srcPtr, size_t srcSize, const unsigned char * dstPtr, size_t dstSize )

inline

Test if 2 areas of memory areas are overlapping.

Test if 2 areas of memory area overlapping.

check if 2 memory regions are overlapping

Move()

__forceinline void Memory::Move	(	const void *	from,
		void *	to,
		size_t	numBytes )

Move a chunk of memory, can handle overlapping regions.

MoveElements()

template<typename T >

__forceinline void Memory::MoveElements	(	const T *	from,
		T *	to,
		size_t	numElements )

Move a chunk of memory, can handle overlapping regions.

Realloc()

void * Memory::Realloc	(	HeapType	heapType,
		void *	ptr,
		size_t	size )

Re-Allocate a block of memory from one of the global heaps.

Reallocate a block of memory.

re-allocate a chunk of memory

NOTE that this function may also be used to shrink a memory block!

SetupHeaps()

void Memory::SetupHeaps

(

)

Setup the global heaps.

This method is called once at application startup from Core::SysFunc::Setup() to setup the various Nebula heaps.

This method is called by SysFunc::Setup() to setup the different heap types.

This method can be tuned to define the start size of the heaps and whether the heap may grow or not (non-growing heaps may be especially useful on console platforms without memory paging).

Variable Documentation

Heaps

HANDLE volatile Memory::Heaps = { NULL }

Heap pointers are defined here.

Call ValidateHeap() to check whether a heap already has been setup, and to setup the heap if not.

HeapTypeAllocCount

long volatile Memory::HeapTypeAllocCount = { 0 }

HeapTypeAllocSize

long volatile Memory::HeapTypeAllocSize = { 0 }

MemoryLoggingEnabled

bool volatile Memory::MemoryLoggingEnabled = false

MemoryLoggingHeapType

HeapType volatile Memory::MemoryLoggingHeapType = InvalidHeapType

MemoryLoggingThreshold

unsigned int volatile Memory::MemoryLoggingThreshold = 0

MemoryLoogingHeapType

HeapType volatile Memory::MemoryLoogingHeapType

extern

NUM_BINS_PER_BUCKET

constexpr uint Memory::NUM_BINS_PER_BUCKET = 0x10

staticconstexpr

NUM_BUCKETS

constexpr uint Memory::NUM_BUCKETS = 0x20

staticconstexpr

PosixProcessHeap

void* volatile Memory::PosixProcessHeap = 0

TotalAllocCount

long volatile Memory::TotalAllocCount = 0

TotalAllocSize

long volatile Memory::TotalAllocSize = 0

Win32ProcessHeap

HANDLE volatile Memory::Win32ProcessHeap = 0