Heaps and multiple heaps

A heap is the logical structure of memory manager. The heap containsthe free list of available memory blocks and various parameters for fine tuning allocations.

The memory manager automatically creates a heap at startup and all allocations will come from this heap unless additional heaps are created. For nearly all applications this is all that is needed. However sometimes you would like one set of allocations to be completely separate from others.

For example, consider this. You have an application that is about to perform an action that will require a fair amount of memory, but only for a short period of time. You might want to put these allocations in their own heap and then free the heap back to the operating system when you are finished with the operation. This keeps your normal heap from inflating to a given size and remaining at that size even though your application will not likely be using this additional memory. This helps your application be a "nice" application and use the operating system resources as efficiently as possible.

To use additional heaps you must first allocate a heap, AllocHeap,and save the heap handle returned by the function. The memory manager provides APIsthat use a current default heap, and APIs that use a heap passed as a parameter.You can change the default heap in various ways. The most common way is to use theheap stack. With this you can set a new heap as the default heap and push the currentheap onto an internal heap stack. You can then perform your allocation(s) and deallocation(s)and then pop the old heap from the heap stack restoring it as the default.

Heap management functions

AllocHeap, DeallocHeap, GetHeap, UseHeap, PushHeap, PopHeap,ClearHeapStack

A heap has a memory source. The heap memory source is used toobtain additional memory for the free list. The memory source defaults to the operatingsystem. You can redirect these allocation calls to your own procedures to obtainmemory from some other source. The procedure SetMemorySource is used to change thememory source for a heap.

FreeHeap. This procedure releases all memory allocated by the memory manager back to the memory source, or source heap. Even if you have not deallocated a memory block back into the heap, that pointer becomes invalid after this call. You should deallocate all memory allocated from the heap, or your code should understand that pointers to this memory become invalid after this call. You should reinitialize your pointers after this call.

ClearHeap. This procedure resets the free list of the heap to the memory allocated from the memory source or source heap. Even if you have not deallocated a memory block back into the heap, that pointer should be considered invalid after this call. You should deallocate all memory allocated from the heap, or your code should understand that pointers to this memory become invalid after this call. You should reinitialize your pointers after this call. Think of this as an instant, super fast, deallocate everything.

The compiler in the development system uses these functions andwe will use this as an example of their use. All programs that use allocated memoryinitialize their lists, trees and tables to NIL at startup. The compiler puts thisinitialization in procedures so it can call them at any time. After the compilerhas compiled a file it has substantial data structures allocated, and these mustbe freed before the next file is to be compiled. Doing all this deallocation wouldtake time so the compiler just calls ClearHeap, and then calls the initializationprocedures to reset all the data structure pointers to their startup empty state.The compiler maintains two heaps because some memory it does not want deallocatedacross multiple compiles and it allocates this memory from a different heap. Afterthe compiler is finished compiling all files that needed to be compiled during asingle environment "build" it calls FreeHeap to release all it's memoryback to the operating system. This memory is then available for the linker, debugpacker and other programs to use and therefore minimizing the amount of memory neededto use the development system.

You can determine memory usage statistics about a specific heap or the sum of all heaps managed by the memory manager. These calls are MemoryInUse, MaxMemoryUsed and HeapMemory.