You can create a fixed-size heap, or a dynamically-sized heap. With a fixed-size heap, the initial block of memory must be large enough to satisfy all allocation requests made to it. With a dynamically-sized heap, the heap can expand and contract as your program needs demand.
Heap_t fixedHeap; /* this is the "heap handle" */ /* get memory for internal info plus 5000 bytes for the heap */ static char block[_HEAP_MIN_SIZE + 5000];The internal information requires a minimum set of bytes, specified by the _HEAP_MIN_SIZE macro (defined in umalloc.h). You can add the amount of memory your program requires to this value to determine the size of the block you need to get. Once the block is fully allocated, further allocation requests to the heap will fail.
After you have allocated a block of memory, you create the heap with _ucreate, and specify the type of memory for the heap, regular or shared. For example:
fixedHeap = _ucreate(block, (_HEAP_MIN_SIZE+5000), /* block to use */
!_BLOCK_CLEAN, /* memory is not set to 0 */
_HEAP_REGULAR, /* regular memory */
NULL, NULL); /* functions for expanding and shrinking
a dynamically-sized heap */
The !_BLOCK_CLEAN parameter indicates that the memory in the block has not been initialized to 0. If it were set to 0 (for example, by memset), you would specify _BLOCK_CLEAN. The calloc and _ucalloc functions use this information to improve their efficiency; if the memory is already initialized to 0, they don't need to initialize it.
The fourth parameter indicates the type of memory the heap contains: regular (_HEAP_REGULAR) or shared (_HEAP_SHARED).
Use _HEAP_REGULAR for regular memory. Most programs use regular memory. This is the type provided by the default run-time heap. Use _HEAP_SHARED for shared memory. Heaps of shared memory can be shared between processes or applications.
For a fixed-size heap, the last two parameters are always NULL.
With the XL C/C++ default heap, when not enough storage is available to fulfill a malloc request, the runtime environment gets additional storage from the system. Similarly, when you minimize the heap with _heapmin or when your program ends, the runtime environment returns the memory to the operating system.
When you create an expandable heap, you provide your own functions to do this work, which you can name however you choose. You specify pointers to these functions as the last two parameters to _ucreate (instead of the NULL pointers you use to create a fixed-size heap). For example:
Heap_t growHeap;
static char block[_HEAP_MIN_SIZE]; /* get block */
growHeap = _ucreate(block, _HEAP_MIN_SIZE, /* starting block */
!_BLOCK_CLEAN, /* memory not set to 0 */
_HEAP_REGULAR, /* regular memory */
expandHeap, /* function to expand heap */
shrinkHeap); /* function to shrink heap */