FGPUDefragAllocator

Simple best fit allocator, splitting and coalescing whenever/ wherever possible.

Windows
MacOS
Linux

References

Module

RHI

Header

/Engine/Source/Runtime/RHI/Public/GPUDefragAllocator.h

Include

#include "GPUDefragAllocator.h"

Syntax

class FGPUDefragAllocator

Remarks

Simple best fit allocator, splitting and coalescing whenever/ wherever possible. NOT THREAD-SAFE.

  • uses TMap to find memory chunk given a Pointer (potentially colliding with malloc/ free from main thread)

  • uses separate linked list for free allocations, assuming that relatively few free chunks due to coalescing

Variables

Name Description

Protected variable

memsize_t

 

AllocatedMemorySize

Protected variable

int32

 

AllocationAlignment

Allocation alignment requirements.

Protected variable

memsize_t

 

AvailableMemorySize

Available memory in uint8s.

Protected variable

bool

 

bBenchmarkMode

When in benchmark mode, don't call any Platform functions.

Protected variable

uint32

 

BlockedCycles

Amount of time blocked by a platform fence since the beginning of the last call to Tick(), in appCycles.

Protected variable

uint64

 

CompletedSyncIndex

Sync index that has been completed, so far.

Protected variable

uint64

 

CurrentLargestHole

Protected variable

int32

 

CurrentNumHoles

Protected variable

uint64

 

CurrentSyncIndex

Ever-increasing index to synchronize all relocations initiated by Tick().

Protected variable

FMemoryChunk &#...

 

FirstChunk

Head of linked list of chunks. Sorted by memory address.

Protected variable

FMemoryChunk &#...

 

FirstFreeChunk

Head of linked list of free chunks. Unsorted.

Protected variable

friend

 

FScopedGPUDefragLock

Protected variable

FMemoryChunk &#...

 

LastChunk

Last chunk in the linked list of chunks (see FirstChunk).

Protected variable

int32

 

MaxNumHoles

Maximum number of disjoint32 free memory regions we've had.

Protected variable

uint8 *

 

MemoryBase

Base of memory pool.

Protected variable

uint64

 

MemorySize

Total size of memory pool, in uint8s.

Protected variable

int64

 

MinLargestHole

Smallest consecutive free memory region we've had.

Protected variable

int32

 

NumCanceledAsyncRequests

Total number of async requests that has been canceled so far.

Protected variable

int32

 

NumFinishedAsyncAllocations

Total number of async allocations successfully completed so far.

Protected variable

int32

 

NumFinishedAsyncReallocations

Total number of async reallocations successfully completed so far.

Protected variable

int32

 

NumLockedChunks

Protected variable

int32

 

NumRelocationsInProgress

Number of async relocations that are currently in progress.

Protected variable

memsize_t

 

PaddingWasteSize

Protected variable

TDoubleLinkedLi...

 

PendingFreeChunks

Chunks that couldn't be freed immediately because they were being relocated.

Protected variable

memsize_t

 

PendingMemoryAdjustment

Adjustment to allocated memory, pending all reallocations.

Protected variable

uint64

 

PlatformSyncFence

Platform-specific (GPU) fence, used for synchronizing the Sync Index.

Protected variable

TMap< void *...

 

PointerToChunkMap

Mapping from Pointer to chunk for fast removal.

Protected variable

FSettings

 

Settings

Allocator settings that affect its behavior.

Protected variable

FCriticalSectio...

 

SynchronizationObject

Protected variable

double

 

TimeSpentInAllocator

Cumulative time spent in allocator.

Protected variable

uint64

 

TotalNumBytesRelocated

Total number of uint8s relocated so far.

Protected variable

uint64

 

TotalNumRelocations

Stats.

Constructors

Name Description

Public function

FGPUDefragAllocator()

Constructor, zero initializing all member variables

Destructors

Name Description

Public function Virtual

~FGPUDefragAllocator()

Functions

Name Description

Public function Virtual

void *

 

Allocate

(
    int64 AllocationSize,
    int32 Alignment,
    TStatId InStat,
    bool bAllowFailure
)

Allocate physical memory.

Protected function

FMemoryChunk...

 

AllocateChunk

(
    FMemoryChunk* FreeChunk,
    int64 AllocationSize,
    bool bAsync,
    bool bDoValidation
)

Marks the specified chunk as 'allocated' and updates tracking variables.

Public function

void

 

Benchmark

(
    int32 MinChunkSize,
    int32 MaxChunkSize,
    float FreeRatio,
    float LockRatio,
    bool bFullDefrag,
    bool bSaveImages,
    const TCHAR* Filename
)

Performs a benchmark of the allocator and outputs the result to the log.

Public function

void

 

BlockOnAsyncReallocation

(
    FAsyncReallocationRequest* Req...
)

Blocks the calling thread until the specified request has been completed.

Protected function

void

 

BlockOnFence()

Blocks the calling thread until the current sync fence has been completed.

Protected function

void

 

BlockOnSyncIndex

(
    uint32 SyncIndex
)

Blocks the calling thread until the specified sync index has been completed.

Public function

void

 

CancelAsyncReallocation

(
    FAsyncReallocationRequest* Req...,
    const void* CurrentBaseAddress
)

Cancels the specified reallocation request.

Protected function Const

bool

 

CanRelocate

(
    const FMemoryChunk* Chunk
)

Returns true if the specified chunk is allowed to relocate at this time.

Protected function

void

 

CheckForErrors

(
    bool bCheckSortedFreeList
)

Checks the int32ernal state for errors. (Slow)

Checks the internal state for errors. (Slow)

Protected function

void

 

Coalesce

(
    FMemoryChunk* FreedChunk
)

Merges any adjacent free chunks into the specified free chunk.

Public function

void

 

DefragmentMemory

(
    FRelocationStats& Stats
)

Fully defragments the memory and blocks until it's done.

Public function

void

 

DumpAllocs

(
    FOutputDevice& Ar
)

Dump allocation information.

Protected function

FMemoryChunk...

 

FindAdjacent

(
    FMemoryChunk* UsedChunk,
    bool bAnyChunkType
)

Defrag helper function. Checks if the specified allocation fits within the adjacent free chunk(s).

Protected function

FMemoryChunk...

 

FindAdjacentToHole

(
    FMemoryChunk* FreeChunk
)

Searches for an allocated chunk that would fit within the specified free chunk.

Protected function

FMemoryChunk...

 

FindAny

(
    FMemoryChunk* FreeChunk
)

Searches for an allocated chunk that would fit within the specified free chunk.

Public function

bool

 

FinishAllRelocations()

Blocks the calling thread until all relocations and reallocations that were initiated by Tick() have completed.

Public function Virtual

void

 

Free

(
    void* Pointer
)

Frees allocation associated with the specified Pointer.

Protected function

void

 

FreeChunk

(
    FMemoryChunk* Chunk
)

Marks the specified chunk as 'free' and updates tracking variables.

Protected function

void

 

FullDefragmentation

(
    FRelocationStats& Stats
)

Performs a full defrag and ignores all reallocation requests.

Public function

int64

 

GetAllocatedSize

(
    void* Pointer
)

Returns the amount of memory allocated for the specified address.

Public function Const

int32

 

GetAllocationAlignment()

Public function Const

uint32

 

GetBlockedCycles()

Returns the amount of time blocked by a platform fence since the beginning of the last call to Tick(), in appCycles.

Public function Const

EMemoryEleme...

 

GetChunkType

(
    FMemoryChunk* Chunk
)

Protected function Const

uint32

 

GetCurrentSyncIndex()

Returns the sync index to be completed by the next call to FinishAllRelocations().

Public function

int32

 

GetLargestAvailableAllocation

(
    int32* OutNumFreeChunks
)

Scans the free chunks and returns the largest size you can allocate.

Public function

void

 

GetMemoryLayout

(
    TArray< FMemoryLayoutElement >& Me...
)

Public function Virtual

void

 

GetMemoryStats

(
    int64& OutAllocatedMemorySize,
    int64& OutAvailableMemorySize,
    int64& OutPendingMemoryAdjustment,
    int64& OutPaddingWasteSize
)

Retrieves allocation stats.

Public function

void

 

GetSettings

(
    FSettings& OutSettings
)

Returns the current allocator settings.

Public function

bool

 

GetTextureMemoryVisualizeData

(
    FColor* TextureData,
    int32 SizeX,
    int32 SizeY,
    int32 Pitch,
    const int32 PixelSize
)

Fills a texture with to visualize the texture pool memory.

Public function Const

int64

 

GetTotalSize()

Public function

void *

 

GetUserPayload

(
    const void* Pointer
)

Returns the user payload for an FMemoryChunk

Protected function

FMemoryChunk...

 

Grow

(
    FMemoryChunk* Chunk,
    int64 GrowAmount
)

Tries to immediately grow a memory chunk by moving the base address, without relocating any memory.

Public function Const

bool

 

InBenchmarkMode()

Returns whether we're in benchmark mode or not.

Public function Virtual

void

 

Initialize

(
    uint8* InMemoryBase,
    int64 InMemorySize
)

Public function Virtual

void

 

Initialize

(
    uint8* InMemoryBase,
    int64 InMemorySize,
    int32 InAllocationAlignment
)

Initialize this allocator with a preallocated block of memory.

Protected function

void

 

InsertFence()

Inserts a platform fence and updates the allocator sync index to match.

Public function Static

bool

 

IsAligned

(
    const volatile void* Ptr,
    const uint32 Alignment
)

Public function

bool

 

IsInitialized()

Returns whether allocator has been initialized.

Public function Const

bool

 

IsValidPoolMemory

(
    const void* Pointer
)

Protected function

void

 

LinkFreeChunk

(
    FMemoryChunk* Chunk
)

Frees the passed in chunk and coalesces adjacent free chunks into 'Chunk' if possible.

Public function Virtual

void

 

Lock

(
    const void* Pointer
)

Locks an FMemoryChunk

Protected function

void

 

PartialDefragmentationDownshift

(
    FRelocationStats& Stats,
    double StartTime
)

Performs a partial defrag by shifting down memory to fill holes, in a brute-force manner.

Protected function

void

 

PartialDefragmentationFast

(
    FRelocationStats& Stats,
    double StartTime
)

Performs a partial defrag doing fast checks only. Adjacency and freelist walk.

Protected function

void

 

PartialDefragmentationSlow

(
    FRelocationStats& Stats,
    double StartTime
)

Performs a partial defrag doing slow all chunk search to find used chunks to move that are surrounded by other used chunks That a freechunk walk won't find.

Protected function

void

 

PlatformBlockOnFence

(
    uint64 Fence
)

Blocks the calling thread until all relocations initiated before the fence was added has been fully completed.

Protected function Const

bool

 

PlatformCanRelocate

(
    const void* Source,
    void* UserPayload
)

Allows each platform to decide whether an allocation can be relocated at this time.

Protected function

uint64

 

PlatformInsertFence()

Inserts a fence to synchronize relocations.

Protected function

void

 

PlatformNotifyReallocationFinished

(
    FAsyncReallocationRequest* Fin...,
    void* UserPayload
)

Notifies the platform that an async reallocation request has been completed.

Protected function

void

 

PlatformRelocate

(
    void* Dest,
    const void* Source,
    int64 Size,
    void* UserPayload
)

Copy memory from one location to another.

Public function

void *

 

Reallocate

(
    void* OldBaseAddress,
    int64 NewSize
)

Tries to reallocate texture memory in-place (without relocating), by adjusting the base address of the allocation but keeping the end address the same.

Protected function

void

 

Relocate

(
    FRelocationStats& Stats,
    FMemoryChunk* Dest,
    int64 DestOffset,
    const void* Source,
    int64 Size,
    void* UserPayload
)

Copy memory from one location to another.

Protected function

FMemoryChunk...

 

RelocateAllowed

(
    FMemoryChunk* FreeChunk,
    FMemoryChunk* UsedChunk
)

Performs a partial defrag while trying to process any pending async reallocation requests.

Protected function

FMemoryChunk...

 

RelocateIntoFreeChunk

(
    FRelocationStats& Stats,
    FMemoryChunk* FreeChunk,
    FMemoryChunk* UsedChunk
)

Initiates an async relocation of an allocated chunk into a free chunk.

Public function

void

 

SetSettings

(
    const FSettings& InSettings
)

Sets new allocator settings.

Public function

void

 

SetUserPayload

(
    const void* Pointer,
    void* UserPayload
)

Sets the user payload for an FMemoryChunk

Protected function

FMemoryChunk...

 

Shrink

(
    FMemoryChunk* Chunk,
    int64 ShrinkAmount
)

Immediately shrinks a memory chunk by moving the base address, without relocating any memory.

Protected function

void

 

SortFreeList

(
    int32& NumFreeChunks,
    int64& LargestFreeChunk
)

Sorts the freelist based on increasing base address.

Protected function

void

 

Split

(
    FMemoryChunk* BaseChunk,
    int64 FirstSize
)

Split allocation into two, first chunk being used and second being available.

Public function Virtual

int32

 

Tick

(
    FRelocationStats& Stats,
    bool bPanicDefrag
)

Partially defragments the memory and tries to process all async reallocation requests at the same time.

Public function Virtual

void

 

Unlock

(
    const void* Pointer
)

Unlocks an FMemoryChunk

Classes

Name

Description

Public class

FMemoryChunk

Contains information of a single allocation or free block.

Public struct

FMemoryLayoutElement

Public struct

FRelocationStats

Container for allocator relocation stats.

Public struct

FSettings

Container for allocator settings.

Enums

Name

Description

Public enum

EMemoryElementType

Typedefs

Name

Description

FRequestList

FRequestNode

memsize_t

Allocated memory in uint8s.
Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss