resonance 1.0.1
Loading...
Searching...
No Matches
Heap Class Reference

Boundary-tagged heap over one contiguous block. More...

#include <heap.h>

Public Member Functions

void * Alloc (unsigned nSize, const char *pszFile, int nLine)
 Take a block.
void Free (void *pBlock, const char *pszFile, int nLine)
 Give a block back.
void * Realloc (void *pBlock, unsigned nSize, const char *pszFile, int nLine)
 Resize a block.
int Shrink (unsigned nSize)
 Shorten the whole heap.

Static Public Member Functions

static Heap * Create (void *pBlock, unsigned nSize, unsigned nFlags)
 Build a heap over a block.

Friends

void HHeapDelete (Heap *pHeap)
 Release a heap's backing block.
void HHeapDump (Heap *pHeap, const char *pszPath)
 Write a heap's header, counters, timings, and every node to a file.
void HHeapLogBasicStats (Heap *pHeap)
 Write a heap's counters to the log and to the memory report.

Detailed Description

Boundary-tagged heap over one contiguous block.

Named after Heap.cpp, the file its allocation tag and its out-of-memory report record. The class is not polymorphic and has no RTTI, so it has no vptr. The 40-byte header sits at the front of the block it manages, and the nodes follow it, which is why Create() reports the block pointer as the heap.

The one instance in the image is the arena the embedded Python allocates from, and Py_Initialize() is its only builder. That routine selects the zone called python, queries ZoneGetAvail() for the space left in it with a 2 MiB fallback, takes all of it in one ZoneAlloc(), and builds the heap over that block with kHeapFlagFirstFit and kHeapFlagFatalWhenFull, which is why exhaustion reports Python heap is out of memory! and stops. The game itself does not allocate through this class. The global operator new and its relatives go to the toolchain allocator instead.

A heap therefore sits inside a zone rather than beside one. The chain runs from the toolchain allocator, through the tagged block ZoneCreate() takes for the python zone, through the single ZoneAlloc() that claims the whole zone, to the nodes this class hands out. No step ever returns an interior pointer to the allocator above it, and the zone check in MemFreeTagged() and MemReallocTagged() is what enforces that, because releasing an interior pointer would corrupt the block that owns it.

Every data member is private, because only the methods below and the three heap routines after the class touch them.

Every field name comes from the two dump lines, Heap Info: length: d flags: d and HHeap Stats: nUsedNodes:d nFreeNodes:d nCalls:(M:d R:d F:d) nBytes:d. The doubled H in the second is reproduced from the image.

Member Function Documentation

◆ Create()

Heap * Heap::Create ( void * pBlock,
unsigned nSize,
unsigned nFlags )
static

Build a heap over a block.

The header occupies the first 40 bytes and the usable length is nSize less those bytes. A request with neither fit bit set becomes first-fit.

A null block is meant to make the heap allocate one for itself and record kHeapFlagOwnsBlock, but the shipped code discards the allocation and then builds the heap at address zero. The one caller always supplies a block, so the defect never fires.

Parameters
pBlockThe block to build over, or null to allocate one.
nSizeThe whole block size in bytes, header included.
nFlagsAny combination of the kHeapFlag values.
Returns
The heap, which is the block itself.
Ghidra address:
NTSC-U/C: 0x00552040
Ghidra address:
PAL: 0x00592680

◆ Alloc()

void * Heap::Alloc ( unsigned nSize,
const char * pszFile,
int nLine )

Take a block.

The request is raised to kHeapMinPayloadSize and rounded up to kHeapPayloadAlignment. A node with more than kHeapSplitThreshold bytes to spare is split and the remainder stays free. Exhaustion is fatal when kHeapFlagFatalWhenFull is set and otherwise reports null.

Parameters
nSizeThe payload size in bytes.
pszFileThe requesting file, which only the report uses.
nLineThe requesting line, which only the report uses.
Returns
The payload, or null when no node fits.
Ghidra address:
NTSC-U/C: 0x00551780
Ghidra address:
PAL: 0x00591dc0

◆ Free()

void Heap::Free ( void * pBlock,
const char * pszFile,
int nLine )

Give a block back.

A null block produces no work. The node merges with a free neighbour on either side, and joins the free list only when neither neighbour was free.

Parameters
pBlockThe payload to release.
pszFileThe releasing file, which the shipped body ignores.
nLineThe releasing line, which the shipped body ignores.
Ghidra address:
NTSC-U/C: 0x00551d28
Ghidra address:
PAL: 0x00592368

◆ Realloc()

void * Heap::Realloc ( void * pBlock,
unsigned nSize,
const char * pszFile,
int nLine )

Resize a block.

Growing into a free following node, shrinking in place, and splitting off a remainder all happen without moving the payload. Only a grow that no neighbour can satisfy allocates, copies, and releases.

Parameters
pBlockThe payload to resize.
nSizeThe new payload size in bytes.
pszFileThe requesting file, which the shipped body ignores.
nLineThe requesting line, which the shipped body ignores.
Returns
The payload, which differs from pBlock only when the block moved, or null when the move could not allocate.
Ghidra address:
NTSC-U/C: 0x005519d0
Ghidra address:
PAL: 0x00592010

◆ Shrink()

int Heap::Shrink ( unsigned nSize)

Shorten the whole heap.

Only the trailing free node can be surrendered, so the attempt reports zero when the last node is in use and when the new length would cut into it. On success the backing block is reallocated and the tail node is moved down.

Parameters
nSizeThe new usable length in bytes.
Returns
Non-zero when the heap was shortened.
Ghidra address:
NTSC-U/C: 0x00552138
Ghidra address:
PAL: 0x00592778

◆ HHeapDelete

void HHeapDelete ( Heap * pHeap)
friend

Release a heap's backing block.

Performs no work unless the heap allocated the block itself. The heap is not cleared first and must not be used afterwards.

Parameters
pHeapThe heap.
Ghidra address:
NTSC-U/C: 0x00552108
Ghidra address:
PAL: 0x00592748

◆ HHeapDump

void HHeapDump ( Heap * pHeap,
const char * pszPath )
friend

Write a heap's header, counters, timings, and every node to a file.

Performs no work when the file cannot be opened. The header and the counters also go to the log.

Parameters
pHeapThe heap.
pszPathThe file to write.
Ghidra address:
NTSC-U/C: 0x00551ec8
Ghidra address:
PAL: 0x00592508

◆ HHeapLogBasicStats

void HHeapLogBasicStats ( Heap * pHeap)
friend

Write a heap's counters to the log and to the memory report.

Parameters
pHeapThe heap.
Ghidra address:
NTSC-U/C: 0x00552218
Ghidra address:
PAL: 0x00592858

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