FShrinkableAllocArena Class Reference

The FShrinkableAllocArena provides a configurable Arena buffer that manages allocations with a maximal size, that can shrink over time. It is meant to be used for RLE tiles or any objects with a known maximal size that can shrink. It is perfect for RLE because we know the max size of an incompressible tile, but we don't know the min size until the compression is done. A collection of such shrinkable allocs is subject to a high fragmentation rate. More...

Public Member Functions
	FShrinkableAllocArena (byte_t iArenaSize, byte_t iMaxAllocSize)
	FShrinkableAllocArena (byte_t iMaxAllocSize, uint64 iNumCells)
	FShrinkableAllocArena (const FShrinkableAllocArena &)=delete
	~FShrinkableAllocArena ()
byte_t	ArenaSize () const
void	DebugPrint (int iType=0, int iCol=100) const
void	DefragSelfForce ()
byte_t	FreeMemory () const
bool	IsEmpty () const
bool	IsFull () const
float	LocalFragmentation () const
tClient	Malloc (byte_t iAllocSize=0xFFFFFFFF)
byte_t	MaxAllocSize () const
FShrinkableAllocArena &	operator= (const FShrinkableAllocArena &)=delete
byte_t	TotalMemory () const
void	UnsafeFreeAll ()
byte_t	UsedMemory () const

Static Public Member Functions
static void	Free (tClient iClient)
static bool	Shrink (tClient iClient, byte_t iNewSize)

Friends
class	FShrinkableAllocMemoryPool

Detailed Description

FShrinkableAllocArena allocs initially fixed max size allocations inside its block, and returns "clients" to the allocation, that is, a pointer to an allocation. Using such clients allows us to regularly defragment the Arena, or multiple Arenas if used in a pool, without losing the data if moved to another memory sector.

The Arena block allocates extra bytes to store some information about the memory status and allocation status, to ensure a fixed number of fixed allocations cells are available.

The layout of the buffer is defined as follows:

• [meta][data]
• [data] contains the real data used by the allocation or tile.
• [meta] stores meta information about the allocation such as [client][prev][next]:
  • [client] is a pointer to the allocation, that allows tracking a moving alloc in case of a defrag
  • [prev] is a delta in bytes to the prev metabase
  • [next] is a delta in bytes to the next metabase The very first element of the buffer should have a prev delta of zero, it acts as a sentinel. We also need a way to identify the case when we reach the end of the arena, so we add another sentinel at the end with a next meta size of 0. No other allocation can have a next meta size of 0.

FShrinkableAllocArena has public methods to estimate the local fragmentation of the memory. Fragmentation matters here in an arena with variable size even within a single Arena. The method used to determine fragmentation is arbitrary but serves the purpose of estimating when a defragmentation pass is necessary. It is not as straightforward as for fixed allocations.

A bit of Terminology:

• byte_t, a size in bytes
• tByte, a byte value ( uint8 )
• tAlloc, an allocation ( uint8* )
• Arena, the whole system
• block, the underlying page buffer
• metaBase, the meta info before an alloc
• client, a pointer to an alloc that can change position
• cell, a fixed element in the area that can host an alloc
• chunk, a collection of cells, either free or used

Constructor & Destructor Documentation

~FShrinkableAllocArena()

FShrinkableAllocArena::~FShrinkableAllocArena

(

)

Destructor, destroy the arena. Cleanup the underlying arena block. Make sure all allocations are free before destroying an arena, or it will trigger an assert in debug builds. You can use UnsafeFreeAll() before destruction to ensure it doesn't crash, but only if you know what you're doing. It is possible to do so before program termination, but if clients don't expect this, they will all be deleted without notification and induce a corrupted state within the program.

FShrinkableAllocArena() [1/3]

FShrinkableAllocArena::FShrinkableAllocArena ( byte_t  iArenaSize, byte_t  iMaxAllocSize  )

explicit

Constructor from arena size and alloc size. Make sure to chose an arena size that is greater than the alloc size and that can fit an expected number of fixed cells allocations. It is best to chose an alloc size that is a divisor of arena size, the behaviour is undefined otherwise. Also, take into account that the block size will use space for the meta data, so the number of objects that can fit is actually smaller than expected, even if max alloc is a divisor of arena size. You can compute the extra meta paddings applied for a given number of objects with dedicated methods or see other constructors that will meet these expectations.

FShrinkableAllocArena() [2/3]

FShrinkableAllocArena::FShrinkableAllocArena ( byte_t  iMaxAllocSize, uint64  iNumCells  )

explicit

Constructor from alloc size and number of expected cells or allocs. An arena size will be coomputed so that it can fit an expected number of fixed cells allocations, that is a proper arena size for the buffers plus extra meta pad size.

FShrinkableAllocArena() [3/3]

FShrinkableAllocArena::FShrinkableAllocArena ( const FShrinkableAllocArena &  )

delete

Explicitely deleted copy constructor

Member Function Documentation

ArenaSize()

byte_t FShrinkableAllocArena::ArenaSize

(

)

const

Obtain the arena size in bytes

DebugPrint()

void FShrinkableAllocArena::DebugPrint	(	int	iType = 0,
		int	iCol = 100
	)		const

Get a textual representation of the arena for debug purposes.

DefragSelfForce()

void FShrinkableAllocArena::DefragSelfForce

(

)

Trigger local defragmentation.

Free()

static void FShrinkableAllocArena::Free ( tClient  iClient )

static

Free an allocation and its associated client. It doesn't need to be resident in pool.

FreeMemory()

byte_t FShrinkableAllocArena::FreeMemory

(

)

const

Obtain current free memory as bytes.

IsEmpty()

bool FShrinkableAllocArena::IsEmpty

(

)

const

Checks wether the arena is empty or not.

IsFull()

bool FShrinkableAllocArena::IsFull

(

)

const

Checks wether the arena is full or not.

LocalFragmentation()

float FShrinkableAllocArena::LocalFragmentation

(

)

const

Get the local frag estimation.

Malloc()

tClient FShrinkableAllocArena::Malloc

(

byte_t

iAllocSize = 0xFFFFFFFF

)

Obtain an client to an allocation within this arena. If full or a failure occurs, returns nullptr.

MaxAllocSize()

byte_t FShrinkableAllocArena::MaxAllocSize

(

)

const

Obtain the max alloc size in bytes

operator=()

FShrinkableAllocArena& FShrinkableAllocArena::operator= ( const FShrinkableAllocArena &  )

delete

Explicitely deleted copy assignment operator

Shrink()

static bool FShrinkableAllocArena::Shrink ( tClient  iClient, byte_t  iNewSize  )

static

Shrink an alloc and return if succesful or not. If not succesfull, the alloc remains as before and is still valid, it just didn't shrink.

TotalMemory()

byte_t FShrinkableAllocArena::TotalMemory

(

)

const

Obtain the total theoretical memory for this pool as bytes, given the current number or arenas.

UnsafeFreeAll()

void FShrinkableAllocArena::UnsafeFreeAll

(

)

Free all resident allocations in this arena. Clients are deleted and not notified about their status. This is unsafe and dangerous, unless you're done with all clients.

UsedMemory()

byte_t FShrinkableAllocArena::UsedMemory

(

)

const

Obtain current used memory as bytes.

Friends And Related Function Documentation

FShrinkableAllocMemoryPool

friend class FShrinkableAllocMemoryPool

friend