Memory Management; The Heap (Dynamic Ram Storage) - Texas Instruments TI-89 Developer's Manual

13.

Memory Management

13.1.

The Heap (Dynamic RAM Storage)

The heap is the place where all dynamic data is stored. The heap is organized
around the use of handles. A handle is a WORD (unsigned 16 bit quantity) that
references a block of heap memory. Handles are used so that the heap blocks
can be compressed by garbage collection when the heap becomes fragmented.
In order to use a handle it must first be dereferenced. The dereferenced handle
points to the data in the heap. This pointer is valid as long as nothing is done that
could cause the heap to be compressed. The following routines may cause the
heap to be compressed (the caller must also be aware of other system routines
that call these routines): HeapAlloc, HeapAllocThrow, HeapAllocHigh,
HeapAllocHighThrow, HeapCompress, HeapMax, HeapMoveHigh,
HeapRealloc, and HeapShuffle. After any of these routines are called (either
directly or indirectly), any dereferenced handles must be dereferenced again;
otherwise, the data pointed to by the dereferenced handle may have been
moved. Most estack routines may cause heap compression. If necessary, a heap
block can be locked. Once locked, a heap block will not be moved. This should
only be done when necessary since it causes garbage collection to be inefficient,
creating the possibility that insufficient RAM will be available when needed. Heap
allocation routines accept a DWORD (double-word) length value but the AMS
implementation limits heap allocations to 65,532 bytes.
For an application, all of its data is either stored in the heap (directly or using
routines like the file system) or in the applications static data area. Data placed in
the heap remains even after an app is terminated. All handles returned from
calling any of the heap allocation routines must be freed before an app is
terminated. Files and variables do not have to be deleted but remain until deleted
by the app, deleted by the user or the system is reset.
HeapAlloc, HeapAllocThrow,
HeapAllocHigh,
HeapAllocHighThrow
HeapAvail
HeapCompress
HeapDeref
HeapFree
HeapFreeIndir
TI-89 / TI-92 Plus Developer Guide
— Allocate memory from the heap.
— Return the total amount of free bytes in the heap.
— Coalesce all used heap blocks, deleting any free
blocks from the heap if possible (garbage
collection).
— Dereference a handle, returning a pointer to the
data.
— Free a heap block given its handle.
— Free a heap block given the address of a handle.
Not for Distribution
131
Beta Version January 26, 2001