8.3 Determining heap differences

This file defines heapdiffstart() and heapdiffend(), which must be called in matching pairs. They both take a heapdiff object as their first parameter, which must still be in scope when the matching call to heapdiffend() is made. The heapdiff object is initialised at the call to heapdiffstart() and is finalised when heapdiffend() is called. It must not be modified in between and should be treated as an opaque type. heapdiffend() can only be called once per heapdiff object before requiring that the heapdiff object be reinitialised through a call to heapdiffstart().

The second parameter to heapdiffstart() specifies a set of flags that can be used to control what is written to the mpatrol log. A list of all unfreed memory allocations can be logged with the HD_UNFREED flag and a list of all freed memory allocations can be logged with the HD_FREED flag, although the latter makes use of the `NOFREE' option and can incur a large performance and space penalty, and also relies on the `NOFREE' option being unmodified between the calls to heapdiffstart() and heapdiffend(). Note that marked allocations are not normally logged but this can be changed by adding the HD_MARKED flag.

By default, only a minimal amount of detail is logged for each allocation, but this can be changed with the HD_FULL flag to log full details for each allocation. If the filename and line number for an allocation is known and the `EDIT' or `LIST' option is being used then using HD_VIEW will edit or list the relevant source file at the correct line number, but only if the `EDIT' or `LIST' options are supported.

If the HD_CONTENTS flag is specified then the contents of all current memory allocations will be written to files and then compared with their subsequent contents when heapdiffend() is called. If the heap is large then this option can require a substantial amount of disk space. All of the allocation contents files will be deleted when the matching call to heapdiffend() is made.