This documentation is archived and is not being maintained.

CMemoryState Structure

Provides a convenient way to detect memory leaks in your program.

struct CMemoryState

CMemoryState is a structure and does not have a base class.

A "memory leak" occurs when memory for an object is allocated on the heap but not deallocated when it is no longer required. Such memory leaks can eventually lead to out-of-memory errors. There are several ways to allocate and deallocate memory in your program:

  • Using the malloc/free family of functions from the run-time library.

  • Using the Windows API memory management functions, LocalAlloc/LocalFree and GlobalAlloc/GlobalFree.

  • Using the C++ new and delete operators.

The CMemoryState diagnostics only help detect memory leaks caused when memory allocated using the new operator is not deallocated using delete. The other two groups of memory-management functions are for non-C++ programs, and mixing them with new and delete in the same program is not recommended. An additional macro, DEBUG_NEW, is provided to replace the new operator when you need file and line-number tracking of memory allocations. DEBUG_NEW is used whenever you would normally use the new operator.

As with other diagnostics, the CMemoryState diagnostics are only available in debug versions of your program. A debug version must have the _DEBUG constant defined.

If you suspect your program has a memory leak, you can use the Checkpoint, Difference, and DumpStatistics functions to discover the difference between the memory state (objects allocated) at two different points in program execution. This information can be useful in determining whether a function is cleaning up all the objects it allocates.

If simply knowing where the imbalance in allocation and deallocation occurs does not provide enough information, you can use the DumpAllObjectsSince function to dump all objects allocated since the previous call to Checkpoint. This dump shows the order of allocation, the source file and line where the object was allocated (if you are using DEBUG_NEW for allocation), and the derivation of the object, its address, and its size. DumpAllObjectsSince also calls each object's Dump function to provide information about its current state.

For more information about how to use CMemoryState and other diagnostics, see Debugging MFC Applications.


Declarations of objects of type CMemoryState and calls to member functions should be bracketed by #if defined(_DEBUG)/#endif directives. This causes memory diagnostics to be included only in debugging builds of your program.

Header: afx.h