Texas Instruments TI89 Developer Guide - Page 173

131 13. 13.1. Memory Management 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, - Allocate memory from the heap. HeapAllocHigh, HeapAllocHighThrow HeapAvail - Return the total amount of free bytes in the heap. HeapCompress - Coalesce all used heap blocks, deleting any free blocks from the heap if possible (garbage collection). HeapDeref - Dereference a handle, returning a pointer to the data. HeapFree - Free a heap block given its handle. HeapFreeIndir - Free a heap block given the address of a handle. TI-89 / TI-92 Plus Developer Guide Not for Distribution Beta Version January 26, 2001