View source for Support for Debugging Memory Allocation

__NOTOC__
<!-- ported from http://www-unix.mcs.anl.gov/mpi/mpichold/developer/design/debugmem.htm -->

== Heap Allocation Debugging ==
The MPICH code contains built-in support for tracing and verifying memory allocation. To make use of this support, configure with <code>--enable-g=mem</code> (you may combine <code>mem</code> with other debugging options, such as <code>--enable-g=dbg,log,mem</code>).

The following environment variables, if they are set to the value <code>YES</code> or <code>yes</code>, will change the behavior of the memory allocation routines:

;<code>MPICH_TRMEM_VALIDATE</code>
: Validate all of the allocated memory, checking for damaged headers or overwritten memory sentinels, every time memory is allocated or freed. 
;<code>MPICH_TRMEM_INITZERO</code>
: Initialize allocated and freed memory to zero. Normally, the memory is initialized to <code>0xda</code> to help detect references to uninitialized memory.  Freed memory is filled with <code>0xfc</code> to help detect reads/writes from/to deallocated memory.

During <code>MPI_Finalize</code>, any memory allocated but not freed will be written out.

== Handle Allocation Debugging ==
MPICH also contains separate facilities for allocating object handles (such as <code>MPI_Comm</code>'s) and the associated underlying object.  Similarly, these facilities have debugging code to help with memory errors that is enabled via <code>--enable-g=mem</code>.  You should also add <code>meminit</code> if you intend to debug with valgrind ([[#Valgrind_Integration|see below]])

Newly allocated handles will be filled with <code>0xef</code>.  Freed handles will be filled with <code>0xec</code>.

== Valgrind Integration ==
The old version of the memory debugging code interfered with valgrind's ability to detect uninitialized data.  As of {{changeset|3255}} MPICH contains [http://valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.clientreq Valgrind Client Requests] to prevent this problem when configured with <code>--enable-g=meminit</code>.

If <code>valgrind.h</code> and <code>memcheck.h</code> are not in your default path you will need to add that include path to your configure line.
<pre><nowiki>
 ./configure [your_args_here] --enable-g=meminit CPPFLAGS='-I/path/to/valgrind/includes'
</nowiki></pre>

For example:
<pre><nowiki>
 ./configure --prefix=/sandbox/goodell/mpich-installed --enable-g=dbg,mem,meminit CPPFLAGS='-I/usr/include/valgrind'
</nowiki></pre>

If configure can't find these two headers then valgrind may not report certain types of errors when <code>--enable-g=mem</code> is specified.  Also, if you intend to use valgrind with MPICH you should generally configure with <code>--enable-g=dbg,meminit</code> at the very least.  This will get you stack traces and prevent several known false positives from being reported as well as the false negative prevention that has been mentioned.

[[Category:Design Documents]]

<!-- vim: set ft=wikipedia : -->