Heap Management Functions

The DP4 C library contains a set of functions for heap management. These functions can be used in place of the standard C library functions malloc() and free(). Unless you define the symbol NO_ANSI_POLLUTE dp4capi.h also contains #define that map malloc() and free() to the replacement DP4 functions mallocp() and freep(). The heap functions were originally added to the DP4 library to enable programs using malloc() and free() to be linked with the DP4 module that enabled object code portability. They have been retained, because it is not unknown for the official implementation of the functions to have bugs, and because they are usually smaller than the CRT implementation. Windows programmers should note that, like most other functions in the DP4 C library, they are not thread safe.

The heap management functions are provided as source code, which is memory-model and operating-system independent.The functions are grouped together by module:

• CCNHEAP1.C and CCNHEAP2.C implement the core heap functions and the replacements for the standard C library functions malloc() and free()
• CCNHEAP3.C implements memory reallocation
• CCNHEAP4.C provides functions allowing an existing heap to be completely replaced with a different temporarty one (this is really just for QAB)
• CCHEAPI.C provides code for initialising the heap. You should refer to the documentation of the heap_init() function to find out how this is done, before using the DP4 heap in your own programs.

In addition, the Least Recently Used (LRU) modules, CCLRU.C, CCLRU1.C and CCLRU2.C provide functions for managing doubly linked lists, used by the cache() functions to discard cached data on a least recently used basis. These functions are defined in LRU.H and not dp4capi.h. This code is used, for example, in the implementation of the caching functions. There are functions for:

• Incorporating objects into the linked list
• Creating an item that can be put in the list
• Locking (prevent discarding) of an item in the list
• Unlocking with promotion/demotion of an item in the list

It is your responsibility to intialise the heap. You can write a function to handle memory exhaustion, or use the lru_handler from the LRU modules. There is no internal consistency checking - assigning to discarded pointers and other program errors will cause unpredictable results. If you experience problems, you might consider debugging the program using the heap routines supplied with your compiler, or recompiling the supplied source code with DEBUG defined. DP4 programs initially have no heap, but it can be acquired in one of three ways:

• You can call heap_init().
• You can declare an array which is not used and call freex(array,sizeof(array))
• You can allocate memory from the operating system or use compiler-supplied memory allocation and call freex().