Heap State Reporting Functions

  • Article

Several new functions report the contents of the debug heap at a given moment. To capture a summary snapshot of the state of the heap at a given time, use the _CrtMemState structure defined in CRTDBG.H:

typedef struct _CrtMemState
{
// Pointer to the most recently allocated block:
   struct _CrtMemBlockHeader * pBlockHeader; 
// A counter for each of the 5 types of block:
   long lCounts[_MAX_BLOCKS]; 
// Total bytes allocated in each block type:
   long lSizes[_MAX_BLOCKS];  
// The most bytes allocated at a time up to now:
   long lHighWaterCount;      
// The total bytes allocated at present:
   long lTotalCount;          
} _CrtMemState;

This structure saves a pointer to the first (most recently allocated) block in the debug heap’s linked list. Then, in two arrays, it records how many of each type of memory block (_NORMAL_BLOCK, _CLIENT_BLOCK, _FREE_BLOCK, and so forth) there are in the list, and the number of bytes allocated in each type of block. Finally, it records the highest number of bytes allocated in the heap as a whole up to that point, and the number of bytes currently allocated.

The following functions report the state and contents of the heap, and use the information to help detect memory leaks and other problems:

Function Description
_CrtMemCheckpoint Saves a snapshot of the heap in a _CrtMemState structure supplied by the application.
_CrtMemDifference Compares two memory state structures, saves the difference between them in a third state structure, and returns TRUE if the two states are different.
_CrtMemDumpStatistics Dumps a given _CrtMemState structure. The structure may contain a snapshot of the state of the debug heap at a given moment, or the difference between two snapshots. “Dumping” means reporting the data in a form that a person can understand.
_CrtMemDumpAllObjectsSince Dumps information about all objects allocated since a given snapshot was taken of the heap, or from the start of execution. Every time it dumps a _CLIENT_BLOCK block, it calls a hook function supplied by the application, if one has been installed using _CrtSetDumpClient.
_CrtDumpMemoryLeaks Determines whether any memory leaks occurred since the start of program execution, and if so, it dumps all allocated objects. Every time it dumps a _CLIENT_BLOCK block, it calls a hook function supplied by the application, if one has been installed using _CrtSetDumpClient.