docs/html/ms-manual.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   4 <title>9. Massif: a heap profiler</title>
   5 <link rel="stylesheet" href="vg_basic.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="Valgrind Documentation">
   8 <link rel="up" href="manual.html" title="Valgrind User Manual">
   9 <link rel="prev" href="drd-manual.html" title="8. DRD: a thread error detector">
  10 <link rel="next" href="dh-manual.html" title="10. DHAT: a dynamic heap analysis tool">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
  14 <td width="22px" align="center" valign="middle"><a accesskey="p" href="drd-manual.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
  15 <td width="25px" align="center" valign="middle"><a accesskey="u" href="manual.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td>
  16 <td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td>
  17 <th align="center" valign="middle">Valgrind User Manual</th>
  18 <td width="22px" align="center" valign="middle"><a accesskey="n" href="dh-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
  19 </tr></table></div>
  20 <div class="chapter" title="9. Massif: a heap profiler">
  21 <div class="titlepage"><div><div><h2 class="title">
  22 <a name="ms-manual"></a>9. Massif: a heap profiler</h2></div></div></div>
  23 <div class="toc">
  24 <p><b>Table of Contents</b></p>
  25 <dl>
  26 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.overview">9.1. Overview</a></span></dt>
  27 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.using">9.2. Using Massif and ms_print</a></span></dt>
  28 <dd><dl>
  29 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.anexample">9.2.1. An Example Program</a></span></dt>
  30 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.running-massif">9.2.2. Running Massif</a></span></dt>
  31 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.running-ms_print">9.2.3. Running ms_print</a></span></dt>
  32 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.theoutputpreamble">9.2.4. The Output Preamble</a></span></dt>
  33 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.theoutputgraph">9.2.5. The Output Graph</a></span></dt>
  34 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.thesnapshotdetails">9.2.6. The Snapshot Details</a></span></dt>
  35 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.forkingprograms">9.2.7. Forking Programs</a></span></dt>
  36 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.not-measured">9.2.8. Measuring All Memory in a Process</a></span></dt>
  37 <dt><span class="sect2"><a href="ms-manual.html#ms-manual.acting">9.2.9. Acting on Massif's Information</a></span></dt>
  38 </dl></dd>
  39 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.options">9.3. Massif Command-line Options</a></span></dt>
  40 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.monitor-commands">9.4. Massif Monitor Commands</a></span></dt>
  41 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.clientreqs">9.5. Massif Client Requests</a></span></dt>
  42 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.ms_print-options">9.6. ms_print Command-line Options</a></span></dt>
  43 <dt><span class="sect1"><a href="ms-manual.html#ms-manual.fileformat">9.7. Massif's Output File Format</a></span></dt>
  44 </dl>
  45 </div>
  46 <p>To use this tool, you must specify
  47 <code class="option">--tool=massif</code> on the Valgrind
  48 command line.</p>
  49 <div class="sect1" title="9.1. Overview">
  50 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  51 <a name="ms-manual.overview"></a>9.1. Overview</h2></div></div></div>
  52 <p>Massif is a heap profiler.  It measures how much heap memory your
  53 program uses.  This includes both the useful space, and the extra bytes
  54 allocated for book-keeping and alignment purposes.  It can also
  55 measure the size of your program's stack(s), although it does not do so by
  56 default.</p>
  57 <p>Heap profiling can help you reduce the amount of memory your program
  58 uses.  On modern machines with virtual memory, this provides the following
  59 benefits:</p>
  60 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  61 <li class="listitem"><p>It can speed up your program -- a smaller
  62     program will interact better with your machine's caches and
  63     avoid paging.</p></li>
  64 <li class="listitem"><p>If your program uses lots of memory, it will
  65     reduce the chance that it exhausts your machine's swap
  66     space.</p></li>
  67 </ul></div>
  68 <p>Also, there are certain space leaks that aren't detected by
  69 traditional leak-checkers, such as Memcheck's.  That's because
  70 the memory isn't ever actually lost -- a pointer remains to it --
  71 but it's not in use.  Programs that have leaks like this can
  72 unnecessarily increase the amount of memory they are using over
  73 time.  Massif can help identify these leaks.</p>
  74 <p>Importantly, Massif tells you not only how much heap memory your
  75 program is using, it also gives very detailed information that indicates
  76 which parts of your program are responsible for allocating the heap memory.
  77 </p>
  78 </div>
  79 <div class="sect1" title="9.2. Using Massif and ms_print">
  80 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  81 <a name="ms-manual.using"></a>9.2. Using Massif and ms_print</h2></div></div></div>
  82 <p>First off, as for the other Valgrind tools, you should compile with
  83 debugging info (the <code class="option">-g</code> option).  It shouldn't
  84 matter much what optimisation level you compile your program with, as this
  85 is unlikely to affect the heap memory usage.</p>
  86 <p>Then, you need to run Massif itself to gather the profiling
  87 information, and then run ms_print to present it in a readable way.</p>
  88 <div class="sect2" title="9.2.1. An Example Program">
  89 <div class="titlepage"><div><div><h3 class="title">
  90 <a name="ms-manual.anexample"></a>9.2.1. An Example Program</h3></div></div></div>
  91 <p>An example will make things clear.  Consider the following C program
  92 (annotated with line numbers) which allocates a number of different blocks
  93 on the heap.</p>
  94 <pre class="screen">
  95  1      #include &lt;stdlib.h&gt;
  96  2
  97  3      void g(void)
  98  4      {
  99  5         malloc(4000);
 100  6      }
 101  7
 102  8      void f(void)
 103  9      {
 104 10         malloc(2000);
 105 11         g();
 106 12      }
 107 13
 108 14      int main(void)
 109 15      {
 110 16         int i;
 111 17         int* a[10];
 112 18
 113 19         for (i = 0; i &lt; 10; i++) {
 114 20            a[i] = malloc(1000);
 115 21         }
 116 22
 117 23         f();
 118 24
 119 25         g();
 120 26
 121 27         for (i = 0; i &lt; 10; i++) {
 122 28            free(a[i]);
 123 29         }
 124 30
 125 31         return 0;
 126 32      }
 127 </pre>
 128 </div>
 129 <div class="sect2" title="9.2.2. Running Massif">
 130 <div class="titlepage"><div><div><h3 class="title">
 131 <a name="ms-manual.running-massif"></a>9.2.2. Running Massif</h3></div></div></div>
 132 <p>To gather heap profiling information about the program
 133 <code class="computeroutput">prog</code>, type:</p>
 134 <pre class="screen">
 135 valgrind --tool=massif prog
 136 </pre>
 137 <p>The program will execute (slowly).  Upon completion, no summary
 138 statistics are printed to Valgrind's commentary;  all of Massif's profiling
 139 data is written to a file.  By default, this file is called
 140 <code class="filename">massif.out.&lt;pid&gt;</code>, where
 141 <code class="filename">&lt;pid&gt;</code> is the process ID, although this filename
 142 can be changed with the <code class="option">--massif-out-file</code> option.</p>
 143 </div>
 144 <div class="sect2" title="9.2.3. Running ms_print">
 145 <div class="titlepage"><div><div><h3 class="title">
 146 <a name="ms-manual.running-ms_print"></a>9.2.3. Running ms_print</h3></div></div></div>
 147 <p>To see the information gathered by Massif in an easy-to-read form, use
 148 ms_print.  If the output file's name is
 149 <code class="filename">massif.out.12345</code>, type:</p>
 150 <pre class="screen">
 151 ms_print massif.out.12345</pre>
 152 <p>ms_print will produce (a) a graph showing the memory consumption over
 153 the program's execution, and (b) detailed information about the responsible
 154 allocation sites at various points in the program, including the point of
 155 peak memory allocation.  The use of a separate script for presenting the
 156 results is deliberate:  it separates the data gathering from its
 157 presentation, and means that new methods of presenting the data can be added in
 158 the future.</p>
 159 </div>
 160 <div class="sect2" title="9.2.4. The Output Preamble">
 161 <div class="titlepage"><div><div><h3 class="title">
 162 <a name="ms-manual.theoutputpreamble"></a>9.2.4. The Output Preamble</h3></div></div></div>
 163 <p>After running this program under Massif, the first part of ms_print's
 164 output contains a preamble which just states how the program, Massif and
 165 ms_print were each invoked:</p>
 166 <pre class="screen">
 167 --------------------------------------------------------------------------------
 168 Command:            example
 169 Massif arguments:   (none)
 170 ms_print arguments: massif.out.12797
 171 --------------------------------------------------------------------------------
 172 </pre>
 173 </div>
 174 <div class="sect2" title="9.2.5. The Output Graph">
 175 <div class="titlepage"><div><div><h3 class="title">
 176 <a name="ms-manual.theoutputgraph"></a>9.2.5. The Output Graph</h3></div></div></div>
 177 <p>The next part is the graph that shows how memory consumption occurred
 178 as the program executed:</p>
 179 <pre class="screen">
 180     KB
 181 19.63^                                                                       #
 182      |                                                                       #
 183      |                                                                       #
 184      |                                                                       #
 185      |                                                                       #
 186      |                                                                       #
 187      |                                                                       #
 188      |                                                                       #
 189      |                                                                       #
 190      |                                                                       #
 191      |                                                                       #
 192      |                                                                       #
 193      |                                                                       #
 194      |                                                                       #
 195      |                                                                       #
 196      |                                                                       #
 197      |                                                                       #
 198      |                                                                      :#
 199      |                                                                      :#
 200      |                                                                      :#
 201    0 +-----------------------------------------------------------------------&gt;ki     0                                                                   113.4
 202
 203
 204 Number of snapshots: 25
 205  Detailed snapshots: [9, 14 (peak), 24]
 206 </pre>
 207 <p>Why is most of the graph empty, with only a couple of bars at the very
 208 end?  By default, Massif uses "instructions executed" as the unit of time.
 209 For very short-run programs such as the example, most of the executed
 210 instructions involve the loading and dynamic linking of the program.  The
 211 execution of <code class="computeroutput">main</code> (and thus the heap
 212 allocations) only occur at the very end.  For a short-running program like
 213 this, we can use the <code class="option">--time-unit=B</code> option
 214 to specify that we want the time unit to instead be the number of bytes
 215 allocated/deallocated on the heap and stack(s).</p>
 216 <p>If we re-run the program under Massif with this option, and then
 217 re-run ms_print, we get this more useful graph:</p>
 218 <pre class="screen">
 219 19.63^                                               ###
 220      |                                               #
 221      |                                               #  ::
 222      |                                               #  : :::
 223      |                                      :::::::::#  : :  ::
 224      |                                      :        #  : :  : ::
 225      |                                      :        #  : :  : : :::
 226      |                                      :        #  : :  : : :  ::
 227      |                            :::::::::::        #  : :  : : :  : :::
 228      |                            :         :        #  : :  : : :  : :  ::
 229      |                        :::::         :        #  : :  : : :  : :  : ::
 230      |                     @@@:   :         :        #  : :  : : :  : :  : : @
 231      |                   ::@  :   :         :        #  : :  : : :  : :  : : @
 232      |                :::: @  :   :         :        #  : :  : : :  : :  : : @
 233      |              :::  : @  :   :         :        #  : :  : : :  : :  : : @
 234      |            ::: :  : @  :   :         :        #  : :  : : :  : :  : : @
 235      |         :::: : :  : @  :   :         :        #  : :  : : :  : :  : : @
 236      |       :::  : : :  : @  :   :         :        #  : :  : : :  : :  : : @
 237      |    :::: :  : : :  : @  :   :         :        #  : :  : : :  : :  : : @
 238      |  :::  : :  : : :  : @  :   :         :        #  : :  : : :  : :  : : @
 239    0 +-----------------------------------------------------------------------&gt;KB     0                                                                   29.48
 240
 241 Number of snapshots: 25
 242  Detailed snapshots: [9, 14 (peak), 24]
 243 </pre>
 244 <p>The size of the graph can be changed with ms_print's
 245 <code class="option">--x</code> and <code class="option">--y</code> options.  Each vertical bar
 246 represents a snapshot, i.e. a measurement of the memory usage at a certain
 247 point in time.  If the next snapshot is more than one column away, a
 248 horizontal line of characters is drawn from the top of the snapshot to just
 249 before the next snapshot column.  The text at the bottom show that 25
 250 snapshots were taken for this program, which is one per heap
 251 allocation/deallocation, plus a couple of extras.  Massif starts by taking
 252 snapshots for every heap allocation/deallocation, but as a program runs for
 253 longer, it takes snapshots less frequently.  It also discards older
 254 snapshots as the program goes on;  when it reaches the maximum number of
 255 snapshots (100 by default, although changeable with the
 256 <code class="option">--max-snapshots</code> option) half of them are
 257 deleted.  This means that a reasonable number of snapshots are always
 258 maintained.</p>
 259 <p>Most snapshots are <span class="emphasis"><em>normal</em></span>, and only basic
 260 information is recorded for them.  Normal snapshots are represented in the
 261 graph by bars consisting of ':' characters.</p>
 262 <p>Some snapshots are <span class="emphasis"><em>detailed</em></span>.  Information about
 263 where allocations happened are recorded for these snapshots, as we will see
 264 shortly.  Detailed snapshots are represented in the graph by bars consisting
 265 of '@' characters.  The text at the bottom show that 3 detailed
 266 snapshots were taken for this program (snapshots 9, 14 and 24).  By default,
 267 every 10th snapshot is detailed, although this can be changed via the
 268 <code class="option">--detailed-freq</code> option.</p>
 269 <p>Finally, there is at most one <span class="emphasis"><em>peak</em></span> snapshot.  The
 270 peak snapshot is a detailed snapshot, and records the point where memory
 271 consumption was greatest.  The peak snapshot is represented in the graph by
 272 a bar consisting of '#' characters.  The text at the bottom shows
 273 that snapshot 14 was the peak.</p>
 274 <p>Massif's determination of when the peak occurred can be wrong, for
 275 two reasons.</p>
 276 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 277 <li class="listitem"><p>Peak snapshots are only ever taken after a deallocation
 278   happens.  This avoids lots of unnecessary peak snapshot recordings
 279   (imagine what happens if your program allocates a lot of heap blocks in
 280   succession, hitting a new peak every time).  But it means that if your
 281   program never deallocates any blocks, no peak will be recorded.  It also
 282   means that if your program does deallocate blocks but later allocates to a
 283   higher peak without subsequently deallocating, the reported peak will be
 284   too low.
 285   </p></li>
 286 <li class="listitem"><p>Even with this behaviour, recording the peak accurately
 287   is slow.  So by default Massif records a peak whose size is within 1% of
 288   the size of the true peak.  This inaccuracy in the peak measurement can be
 289   changed with the <code class="option">--peak-inaccuracy</code> option.</p></li>
 290 </ul></div>
 291 <p>The following graph is from an execution of Konqueror, the KDE web
 292 browser.  It shows what graphs for larger programs look like.</p>
 293 <pre class="screen">
 294     MB
 295 3.952^                                                                    #
 296      |                                                                   @#:
 297      |                                                                 :@@#:
 298      |                                                            @@::::@@#:
 299      |                                                            @ :: :@@#::
 300      |                                                          @@@ :: :@@#::
 301      |                                                       @@:@@@ :: :@@#::
 302      |                                                    :::@ :@@@ :: :@@#::
 303      |                                                    : :@ :@@@ :: :@@#::
 304      |                                                  :@: :@ :@@@ :: :@@#::
 305      |                                                @@:@: :@ :@@@ :: :@@#:::
 306      |                           :       ::         ::@@:@: :@ :@@@ :: :@@#:::
 307      |                        :@@:    ::::: ::::@@@:::@@:@: :@ :@@@ :: :@@#:::
 308      |                     ::::@@:  ::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 309      |                    @: ::@@:  ::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 310      |                    @: ::@@:  ::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 311      |                    @: ::@@:::::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 312      |                ::@@@: ::@@:: ::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 313      |             :::::@ @: ::@@:: ::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 314      |           @@:::::@ @: ::@@:: ::: ::::::: @  :::@@:@: :@ :@@@ :: :@@#:::
 315    0 +-----------------------------------------------------------------------&gt;Mi
 316      0                                                                   626.4
 317
 318 Number of snapshots: 63
 319  Detailed snapshots: [3, 4, 10, 11, 15, 16, 29, 33, 34, 36, 39, 41,
 320                       42, 43, 44, 49, 50, 51, 53, 55, 56, 57 (peak)]
 321 </pre>
 322 <p>Note that the larger size units are KB, MB, GB, etc.  As is typical
 323 for memory measurements, these are based on a multiplier of 1024, rather
 324 than the standard SI multiplier of 1000.  Strictly speaking, they should be
 325 written KiB, MiB, GiB, etc.</p>
 326 </div>
 327 <div class="sect2" title="9.2.6. The Snapshot Details">
 328 <div class="titlepage"><div><div><h3 class="title">
 329 <a name="ms-manual.thesnapshotdetails"></a>9.2.6. The Snapshot Details</h3></div></div></div>
 330 <p>Returning to our example, the graph is followed by the detailed
 331 information for each snapshot.  The first nine snapshots are normal, so only
 332 a small amount of information is recorded for each one:</p>
 333 <pre class="screen">
 334 --------------------------------------------------------------------------------
 335   n        time(B)         total(B)   useful-heap(B) extra-heap(B)    stacks(B)
 336 --------------------------------------------------------------------------------
 337   0              0                0                0             0            0
 338   1          1,008            1,008            1,000             8            0
 339   2          2,016            2,016            2,000            16            0
 340   3          3,024            3,024            3,000            24            0
 341   4          4,032            4,032            4,000            32            0
 342   5          5,040            5,040            5,000            40            0
 343   6          6,048            6,048            6,000            48            0
 344   7          7,056            7,056            7,000            56            0
 345   8          8,064            8,064            8,000            64            0
 346 </pre>
 347 <p>Each normal snapshot records several things.</p>
 348 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 349 <li class="listitem"><p>Its number.</p></li>
 350 <li class="listitem"><p>The time it was taken. In this case, the time unit is
 351   bytes, due to the use of
 352   <code class="option">--time-unit=B</code>.</p></li>
 353 <li class="listitem"><p>The total memory consumption at that point.</p></li>
 354 <li class="listitem"><p>The number of useful heap bytes allocated at that point.
 355   This reflects the number of bytes asked for by the
 356   program.</p></li>
 357 <li class="listitem">
 358 <p>The number of extra heap bytes allocated at that point.
 359   This reflects the number of bytes allocated in excess of what the program
 360   asked for.  There are two sources of extra heap bytes.</p>
 361 <p>First, every heap block has administrative bytes associated with it.
 362   The exact number of administrative bytes depends on the details of the
 363   allocator.  By default Massif assumes 8 bytes per block, as can be seen
 364   from the example, but this number can be changed via the
 365   <code class="option">--heap-admin</code> option.</p>
 366 <p>Second, allocators often round up the number of bytes asked for to a
 367   larger number, usually 8 or 16.  This is required to ensure that elements
 368   within the block are suitably aligned.  If N bytes are asked for, Massif
 369   rounds N up to the nearest multiple of the value specified by the
 370   <code class="option"><a class="xref" href="manual-core.html#opt.alignment">--alignment</a></code> option.
 371   </p>
 372 </li>
 373 <li class="listitem"><p>The size of the stack(s).  By default, stack profiling is
 374   off as it slows Massif down greatly.  Therefore, the stack column is zero
 375   in the example.  Stack profiling can be turned on with the
 376   <code class="option">--stacks=yes</code> option.
 377
 378   </p></li>
 379 </ul></div>
 380 <p>The next snapshot is detailed.  As well as the basic counts, it gives
 381 an allocation tree which indicates exactly which pieces of code were
 382 responsible for allocating heap memory:</p>
 383 <pre class="screen">
 384   9          9,072            9,072            9,000            72            0
 385 99.21% (9,000B) (heap allocation functions) malloc/new/new[], --alloc-fns, etc.
 386 -&gt;99.21% (9,000B) 0x804841A: main (example.c:20)
 387 </pre>
 388 <p>The allocation tree can be read from the top down.  The first line
 389 indicates all heap allocation functions such as <code class="function">malloc</code>
 390 and C++ <code class="function">new</code>.  All heap allocations go through these
 391 functions, and so all 9,000 useful bytes (which is 99.21% of all allocated
 392 bytes) go through them.  But how were <code class="function">malloc</code> and new
 393 called?  At this point, every allocation so far has been due to line 20
 394 inside <code class="function">main</code>, hence the second line in the tree.  The
 395 <code class="option">-&gt;</code> indicates that main (line 20) called
 396 <code class="function">malloc</code>.</p>
 397 <p>Let's see what the subsequent output shows happened next:</p>
 398 <pre class="screen">
 399 --------------------------------------------------------------------------------
 400   n        time(B)         total(B)   useful-heap(B) extra-heap(B)    stacks(B)
 401 --------------------------------------------------------------------------------
 402  10         10,080           10,080           10,000            80            0
 403  11         12,088           12,088           12,000            88            0
 404  12         16,096           16,096           16,000            96            0
 405  13         20,104           20,104           20,000           104            0
 406  14         20,104           20,104           20,000           104            0
 407 99.48% (20,000B) (heap allocation functions) malloc/new/new[], --alloc-fns, etc.
 408 -&gt;49.74% (10,000B) 0x804841A: main (example.c:20)
 409 |
 410 -&gt;39.79% (8,000B) 0x80483C2: g (example.c:5)
 411 | -&gt;19.90% (4,000B) 0x80483E2: f (example.c:11)
 412 | | -&gt;19.90% (4,000B) 0x8048431: main (example.c:23)
 413 | |
 414 | -&gt;19.90% (4,000B) 0x8048436: main (example.c:25)
 415 |
 416 -&gt;09.95% (2,000B) 0x80483DA: f (example.c:10)
 417   -&gt;09.95% (2,000B) 0x8048431: main (example.c:23)
 418 </pre>
 419 <p>The first four snapshots are similar to the previous ones.  But then
 420 the global allocation peak is reached, and a detailed snapshot (number 14)
 421 is taken.  Its allocation tree shows that 20,000B of useful heap memory has
 422 been allocated, and the lines and arrows indicate that this is from three
 423 different code locations: line 20, which is responsible for 10,000B
 424 (49.74%);  line 5, which is responsible for 8,000B (39.79%); and line 10,
 425 which is responsible for 2,000B (9.95%).</p>
 426 <p>We can then drill down further in the allocation tree.  For example,
 427 of the 8,000B asked for by line 5, half of it was due to a call from line
 428 11, and half was due to a call from line 25.</p>
 429 <p>In short, Massif collates the stack trace of every single allocation
 430 point in the program into a single tree, which gives a complete picture at
 431 a particular point in time of how and why all heap memory was
 432 allocated.</p>
 433 <p>Note that the tree entries correspond not to functions, but to
 434 individual code locations.  For example, if function <code class="function">A</code>
 435 calls <code class="function">malloc</code>, and function <code class="function">B</code> calls
 436 <code class="function">A</code> twice, once on line 10 and once on line 11, then
 437 the two calls will result in two distinct stack traces in the tree.  In
 438 contrast, if <code class="function">B</code> calls <code class="function">A</code> repeatedly
 439 from line 15 (e.g. due to a loop), then each of those calls will be
 440 represented by the same stack trace in the tree.</p>
 441 <p>Note also that each tree entry with children in the example satisfies an
 442 invariant: the entry's size is equal to the sum of its children's sizes.
 443 For example, the first entry has size 20,000B, and its children have sizes
 444 10,000B, 8,000B, and 2,000B.  In general, this invariant almost always
 445 holds.  However, in rare circumstances stack traces can be malformed, in
 446 which case a stack trace can be a sub-trace of another stack trace.  This
 447 means that some entries in the tree may not satisfy the invariant -- the
 448 entry's size will be greater than the sum of its children's sizes.  This is
 449 not a big problem, but could make the results confusing.  Massif can
 450 sometimes detect when this happens;  if it does, it issues a warning:</p>
 451 <pre class="screen">
 452 Warning: Malformed stack trace detected.  In Massif's output,
 453          the size of an entry's child entries may not sum up
 454          to the entry's size as they normally do.
 455 </pre>
 456 <p>However, Massif does not detect and warn about every such occurrence.
 457 Fortunately, malformed stack traces are rare in practice.</p>
 458 <p>Returning now to ms_print's output, the final part is similar:</p>
 459 <pre class="screen">
 460 --------------------------------------------------------------------------------
 461   n        time(B)         total(B)   useful-heap(B) extra-heap(B)    stacks(B)
 462 --------------------------------------------------------------------------------
 463  15         21,112           19,096           19,000            96            0
 464  16         22,120           18,088           18,000            88            0
 465  17         23,128           17,080           17,000            80            0
 466  18         24,136           16,072           16,000            72            0
 467  19         25,144           15,064           15,000            64            0
 468  20         26,152           14,056           14,000            56            0
 469  21         27,160           13,048           13,000            48            0
 470  22         28,168           12,040           12,000            40            0
 471  23         29,176           11,032           11,000            32            0
 472  24         30,184           10,024           10,000            24            0
 473 99.76% (10,000B) (heap allocation functions) malloc/new/new[], --alloc-fns, etc.
 474 -&gt;79.81% (8,000B) 0x80483C2: g (example.c:5)
 475 | -&gt;39.90% (4,000B) 0x80483E2: f (example.c:11)
 476 | | -&gt;39.90% (4,000B) 0x8048431: main (example.c:23)
 477 | |
 478 | -&gt;39.90% (4,000B) 0x8048436: main (example.c:25)
 479 |
 480 -&gt;19.95% (2,000B) 0x80483DA: f (example.c:10)
 481 | -&gt;19.95% (2,000B) 0x8048431: main (example.c:23)
 482 |
 483 -&gt;00.00% (0B) in 1+ places, all below ms_print's threshold (01.00%)
 484 </pre>
 485 <p>The final detailed snapshot shows how the heap looked at termination.
 486 The 00.00% entry represents the code locations for which memory was
 487 allocated and then freed (line 20 in this case, the memory for which was
 488 freed on line 28).  However, no code location details are given for this
 489 entry;  by default, Massif only records the details for code locations
 490 responsible for more than 1% of useful memory bytes, and ms_print likewise
 491 only prints the details for code locations responsible for more than 1%.
 492 The entries that do not meet this threshold are aggregated.  This avoids
 493 filling up the output with large numbers of unimportant entries.  The
 494 thresholds can be changed with the
 495 <code class="option">--threshold</code> option that both Massif and
 496 ms_print support.</p>
 497 </div>
 498 <div class="sect2" title="9.2.7. Forking Programs">
 499 <div class="titlepage"><div><div><h3 class="title">
 500 <a name="ms-manual.forkingprograms"></a>9.2.7. Forking Programs</h3></div></div></div>
 501 <p>If your program forks, the child will inherit all the profiling data that
 502 has been gathered for the parent.</p>
 503 <p>If the output file format string (controlled by
 504 <code class="option">--massif-out-file</code>) does not contain <code class="option">%p</code>, then
 505 the outputs from the parent and child will be intermingled in a single output
 506 file, which will almost certainly make it unreadable by ms_print.</p>
 507 </div>
 508 <div class="sect2" title="9.2.8. Measuring All Memory in a Process">
 509 <div class="titlepage"><div><div><h3 class="title">
 510 <a name="ms-manual.not-measured"></a>9.2.8. Measuring All Memory in a Process</h3></div></div></div>
 511 <p>
 512 It is worth emphasising that by default Massif measures only heap memory, i.e.
 513 memory allocated with
 514 <code class="function">malloc</code>,
 515 <code class="function">calloc</code>,
 516 <code class="function">realloc</code>,
 517 <code class="function">memalign</code>,
 518 <code class="function">new</code>,
 519 <code class="function">new[]</code>,
 520 and a few other, similar functions.  (And it can optionally measure stack
 521 memory, of course.)  This means it does <span class="emphasis"><em>not</em></span> directly
 522 measure memory allocated with lower-level system calls such as
 523 <code class="function">mmap</code>,
 524 <code class="function">mremap</code>, and
 525 <code class="function">brk</code>.
 526 </p>
 527 <p>
 528 Heap allocation functions such as <code class="function">malloc</code> are built on
 529 top of these system calls.  For example, when needed, an allocator will
 530 typically call <code class="function">mmap</code> to allocate a large chunk of
 531 memory, and then hand over pieces of that memory chunk to the client program
 532 in response to calls to <code class="function">malloc</code> et al.  Massif directly
 533 measures only these higher-level <code class="function">malloc</code> et al calls,
 534 not the lower-level system calls.
 535 </p>
 536 <p>
 537 Furthermore, a client program may use these lower-level system calls
 538 directly to allocate memory.  By default, Massif does not measure these.  Nor
 539 does it measure the size of code, data and BSS segments.  Therefore, the
 540 numbers reported by Massif may be significantly smaller than those reported by
 541 tools such as <code class="filename">top</code> that measure a program's total size in
 542 memory.
 543 </p>
 544 <p>
 545 However, if you wish to measure <span class="emphasis"><em>all</em></span> the memory used by
 546 your program, you can use the <code class="option">--pages-as-heap=yes</code>.  When this
 547 option is enabled, Massif's normal heap block profiling is replaced by
 548 lower-level page profiling.  Every page allocated via
 549 <code class="function">mmap</code> and similar system calls is treated as a distinct
 550 block.  This means that code, data and BSS segments are all measured, as they
 551 are just memory pages.  Even the stack is measured, since it is ultimately
 552 allocated (and extended when necessary) via <code class="function">mmap</code>;  for
 553 this reason <code class="option">--stacks=yes</code> is not allowed in conjunction with
 554 <code class="option">--pages-as-heap=yes</code>.
 555 </p>
 556 <p>
 557 After <code class="option">--pages-as-heap=yes</code> is used, ms_print's output is
 558 mostly unchanged.  One difference is that the start of each detailed snapshot
 559 says:
 560 </p>
 561 <pre class="screen">
 562 (page allocation syscalls) mmap/mremap/brk, --alloc-fns, etc.
 563 </pre>
 564 <p>instead of the usual</p>:
 565
 566 <pre class="screen">
 567 (heap allocation functions) malloc/new/new[], --alloc-fns, etc.
 568 </pre>
 569 <p>
 570 The stack traces in the output may be more difficult to read, and interpreting
 571 them may require some detailed understanding of the lower levels of a program
 572 like the memory allocators.  But for some programs having the full information
 573 about memory usage can be very useful.
 574 </p>
 575 </div>
 576 <div class="sect2" title="9.2.9. Acting on Massif's Information">
 577 <div class="titlepage"><div><div><h3 class="title">
 578 <a name="ms-manual.acting"></a>9.2.9. Acting on Massif's Information</h3></div></div></div>
 579 <p>Massif's information is generally fairly easy to act upon.  The
 580 obvious place to start looking is the peak snapshot.</p>
 581 <p>It can also be useful to look at the overall shape of the graph, to
 582 see if memory usage climbs and falls as you expect;  spikes in the graph
 583 might be worth investigating.</p>
 584 <p>The detailed snapshots can get quite large.  It is worth viewing them
 585 in a very wide window.   It's also a good idea to view them with a text
 586 editor.  That makes it easy to scroll up and down while keeping the cursor
 587 in a particular column, which makes following the allocation chains easier.
 588 </p>
 589 </div>
 590 </div>
 591 <div class="sect1" title="9.3. Massif Command-line Options">
 592 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 593 <a name="ms-manual.options"></a>9.3. Massif Command-line Options</h2></div></div></div>
 594 <p>Massif-specific command-line options are:</p>
 595 <div class="variablelist">
 596 <a name="ms.opts.list"></a><dl>
 597 <dt>
 598 <a name="opt.heap"></a><span class="term">
 599       <code class="option">--heap=&lt;yes|no&gt; [default: yes] </code>
 600     </span>
 601 </dt>
 602 <dd><p>Specifies whether heap profiling should be done.</p></dd>
 603 <dt>
 604 <a name="opt.heap-admin"></a><span class="term">
 605       <code class="option">--heap-admin=&lt;size&gt; [default: 8] </code>
 606     </span>
 607 </dt>
 608 <dd><p>If heap profiling is enabled, gives the number of administrative
 609       bytes per block to use.  This should be an estimate of the average,
 610       since it may vary.  For example, the allocator used by
 611       glibc on Linux requires somewhere between 4 to
 612       15 bytes per block, depending on various factors.  That allocator also
 613       requires admin space for freed blocks, but Massif cannot
 614       account for this.</p></dd>
 615 <dt>
 616 <a name="opt.stacks"></a><span class="term">
 617       <code class="option">--stacks=&lt;yes|no&gt; [default: no] </code>
 618     </span>
 619 </dt>
 620 <dd><p>Specifies whether stack profiling should be done.  This option
 621       slows Massif down greatly, and so is off by default.  Note that Massif
 622       assumes that the main stack has size zero at start-up.  This is not
 623       true, but doing otherwise accurately is difficult.  Furthermore,
 624       starting at zero better indicates the size of the part of the main
 625       stack that a user program actually has control over.</p></dd>
 626 <dt>
 627 <a name="opt.pages-as-heap"></a><span class="term">
 628       <code class="option">--pages-as-heap=&lt;yes|no&gt; [default: no] </code>
 629     </span>
 630 </dt>
 631 <dd><p>Tells Massif to profile memory at the page level rather
 632         than at the malloc'd block level.  See above for details.
 633       </p></dd>
 634 <dt>
 635 <a name="opt.depth"></a><span class="term">
 636       <code class="option">--depth=&lt;number&gt; [default: 30] </code>
 637     </span>
 638 </dt>
 639 <dd><p>Maximum depth of the allocation trees recorded for detailed
 640       snapshots.  Increasing it will make Massif run somewhat more slowly,
 641       use more memory, and produce bigger output files.</p></dd>
 642 <dt>
 643 <a name="opt.alloc-fn"></a><span class="term">
 644       <code class="option">--alloc-fn=&lt;name&gt; </code>
 645     </span>
 646 </dt>
 647 <dd>
 648 <p>Functions specified with this option will be treated as though
 649       they were a heap allocation function such as
 650       <code class="function">malloc</code>.  This is useful for functions that are
 651       wrappers to <code class="function">malloc</code> or <code class="function">new</code>,
 652       which can fill up the allocation trees with uninteresting information.
 653       This option can be specified multiple times on the command line, to
 654       name multiple functions.</p>
 655 <p>Note that the named function will only be treated this way if it is
 656       the top entry in a stack trace, or just below another function treated
 657       this way.  For example, if you have a function
 658       <code class="function">malloc1</code> that wraps <code class="function">malloc</code>,
 659       and <code class="function">malloc2</code> that wraps
 660       <code class="function">malloc1</code>, just specifying
 661       <code class="option">--alloc-fn=malloc2</code> will have no effect.  You need to
 662       specify <code class="option">--alloc-fn=malloc1</code> as well.  This is a little
 663       inconvenient, but the reason is that checking for allocation functions
 664       is slow, and it saves a lot of time if Massif can stop looking through
 665       the stack trace entries as soon as it finds one that doesn't match
 666       rather than having to continue through all the entries.</p>
 667 <p>Note that C++ names are demangled.  Note also that overloaded
 668       C++ names must be written in full.  Single quotes may be necessary to
 669       prevent the shell from breaking them up.  For example:
 670 </p>
 671 <pre class="screen">
 672 --alloc-fn='operator new(unsigned, std::nothrow_t const&amp;)'
 673 </pre>
 674 <p>
 675       </p>
 676 </dd>
 677 <dt>
 678 <a name="opt.ignore-fn"></a><span class="term">
 679       <code class="option">--ignore-fn=&lt;name&gt; </code>
 680     </span>
 681 </dt>
 682 <dd>
 683 <p>Any direct heap allocation (i.e. a call to
 684       <code class="function">malloc</code>, <code class="function">new</code>, etc, or a call
 685       to a function named by an <code class="option">--alloc-fn</code>
 686       option) that occurs in a function specified by this option will be
 687       ignored.  This is mostly useful for testing purposes.  This option can
 688       be specified multiple times on the command line, to name multiple
 689       functions.
 690       </p>
 691 <p>Any <code class="function">realloc</code> of an ignored block will
 692       also be ignored, even if the <code class="function">realloc</code> call does
 693       not occur in an ignored function.  This avoids the possibility of
 694       negative heap sizes if ignored blocks are shrunk with
 695       <code class="function">realloc</code>.
 696       </p>
 697 <p>The rules for writing C++ function names are the same as
 698       for <code class="option">--alloc-fn</code> above.
 699       </p>
 700 </dd>
 701 <dt>
 702 <a name="opt.threshold"></a><span class="term">
 703       <code class="option">--threshold=&lt;m.n&gt; [default: 1.0] </code>
 704     </span>
 705 </dt>
 706 <dd><p>The significance threshold for heap allocations, as a
 707       percentage of total memory size.  Allocation tree entries that account
 708       for less than this will be aggregated.  Note that this should be
 709       specified in tandem with ms_print's option of the same name.</p></dd>
 710 <dt>
 711 <a name="opt.peak-inaccuracy"></a><span class="term">
 712       <code class="option">--peak-inaccuracy=&lt;m.n&gt; [default: 1.0] </code>
 713     </span>
 714 </dt>
 715 <dd><p>Massif does not necessarily record the actual global memory
 716       allocation peak;  by default it records a peak only when the global
 717       memory allocation size exceeds the previous peak by at least 1.0%.
 718       This is because there can be many local allocation peaks along the way,
 719       and doing a detailed snapshot for every one would be expensive and
 720       wasteful, as all but one of them will be later discarded.  This
 721       inaccuracy can be changed (even to 0.0%) via this option, but Massif
 722       will run drastically slower as the number approaches zero.</p></dd>
 723 <dt>
 724 <a name="opt.time-unit"></a><span class="term">
 725       <code class="option">--time-unit=&lt;i|ms|B&gt; [default: i] </code>
 726     </span>
 727 </dt>
 728 <dd><p>The time unit used for the profiling.  There are three
 729       possibilities: instructions executed (i), which is good for most
 730       cases; real (wallclock) time (ms, i.e. milliseconds), which is
 731       sometimes useful; and bytes allocated/deallocated on the heap and/or
 732       stack (B), which is useful for very short-run programs, and for
 733       testing purposes, because it is the most reproducible across different
 734       machines.</p></dd>
 735 <dt>
 736 <a name="opt.detailed-freq"></a><span class="term">
 737       <code class="option">--detailed-freq=&lt;n&gt; [default: 10] </code>
 738     </span>
 739 </dt>
 740 <dd><p>Frequency of detailed snapshots.  With
 741       <code class="option">--detailed-freq=1</code>, every snapshot is
 742       detailed.</p></dd>
 743 <dt>
 744 <a name="opt.max-snapshots"></a><span class="term">
 745       <code class="option">--max-snapshots=&lt;n&gt; [default: 100] </code>
 746     </span>
 747 </dt>
 748 <dd><p>The maximum number of snapshots recorded.  If set to N, for all
 749       programs except very short-running ones, the final number of snapshots
 750       will be between N/2 and N.</p></dd>
 751 <dt>
 752 <a name="opt.massif-out-file"></a><span class="term">
 753       <code class="option">--massif-out-file=&lt;file&gt; [default: massif.out.%p] </code>
 754     </span>
 755 </dt>
 756 <dd><p>Write the profile data to <code class="computeroutput">file</code>
 757       rather than to the default output file,
 758       <code class="computeroutput">massif.out.&lt;pid&gt;</code>.  The
 759       <code class="option">%p</code> and <code class="option">%q</code> format specifiers can be
 760       used to embed the process ID and/or the contents of an environment
 761       variable in the name, as is the case for the core option
 762       <code class="option"><a class="xref" href="manual-core.html#opt.log-file">--log-file</a></code>.
 763       </p></dd>
 764 </dl>
 765 </div>
 766 </div>
 767 <div class="sect1" title="9.4. Massif Monitor Commands">
 768 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 769 <a name="ms-manual.monitor-commands"></a>9.4. Massif Monitor Commands</h2></div></div></div>
 770 <p>The Massif tool provides monitor commands handled by the Valgrind
 771 gdbserver (see <a class="xref" href="manual-core-adv.html#manual-core-adv.gdbserver-commandhandling" title="3.2.5. Monitor command handling by the Valgrind gdbserver">Monitor command handling by the Valgrind gdbserver</a>).
 772 </p>
 773 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 774 <li class="listitem"><p><code class="varname">snapshot [&lt;filename&gt;]</code> requests
 775     to take a snapshot and save it in the given &lt;filename&gt;
 776     (default massif.vgdb.out).
 777     </p></li>
 778 <li class="listitem"><p><code class="varname">detailed_snapshot [&lt;filename&gt;]</code>
 779     requests to take a detailed snapshot and save it in the given
 780     &lt;filename&gt; (default massif.vgdb.out).
 781     </p></li>
 782 </ul></div>
 783 </div>
 784 <div class="sect1" title="9.5. Massif Client Requests">
 785 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 786 <a name="ms-manual.clientreqs"></a>9.5. Massif Client Requests</h2></div></div></div>
 787 <p>Massif does not have a <code class="filename">massif.h</code> file, but it does
 788 implement two of the core client requests:
 789 <code class="function">VALGRIND_MALLOCLIKE_BLOCK</code> and
 790 <code class="function">VALGRIND_FREELIKE_BLOCK</code>;  they are described in
 791 <a class="xref" href="manual-core-adv.html#manual-core-adv.clientreq" title="3.1. The Client Request mechanism">The Client Request mechanism</a>.
 792 </p>
 793 </div>
 794 <div class="sect1" title="9.6. ms_print Command-line Options">
 795 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 796 <a name="ms-manual.ms_print-options"></a>9.6. ms_print Command-line Options</h2></div></div></div>
 797 <p>ms_print's options are:</p>
 798 <div class="variablelist">
 799 <a name="ms_print.opts.list"></a><dl>
 800 <dt><span class="term">
 801       <code class="option">-h --help </code>
 802     </span></dt>
 803 <dd><p>Show the help message.</p></dd>
 804 <dt><span class="term">
 805       <code class="option">--version </code>
 806     </span></dt>
 807 <dd><p>Show the version number.</p></dd>
 808 <dt><span class="term">
 809       <code class="option">--threshold=&lt;m.n&gt; [default: 1.0] </code>
 810     </span></dt>
 811 <dd><p>Same as Massif's <code class="option">--threshold</code> option, but
 812       applied after profiling rather than during.</p></dd>
 813 <dt><span class="term">
 814       <code class="option">--x=&lt;4..1000&gt; [default: 72]</code>
 815     </span></dt>
 816 <dd><p>Width of the graph, in columns.</p></dd>
 817 <dt><span class="term">
 818       <code class="option">--y=&lt;4..1000&gt; [default: 20] </code>
 819     </span></dt>
 820 <dd><p>Height of the graph, in rows.</p></dd>
 821 </dl>
 822 </div>
 823 </div>
 824 <div class="sect1" title="9.7. Massif's Output File Format">
 825 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 826 <a name="ms-manual.fileformat"></a>9.7. Massif's Output File Format</h2></div></div></div>
 827 <p>Massif's file format is plain text (i.e. not binary) and deliberately
 828 easy to read for both humans and machines.  Nonetheless, the exact format
 829 is not described here.  This is because the format is currently very
 830 Massif-specific.  In the future we hope to make the format more general, and
 831 thus suitable for possible use with other tools.  Once this has been done,
 832 the format will be documented here.</p>
 833 </div>
 834 </div>
 835 <div>
 836 <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
 837 <tr>
 838 <td rowspan="2" width="40%" align="left">
 839 <a accesskey="p" href="drd-manual.html">&lt;&lt; 8. DRD: a thread error detector</a> </td>
 840 <td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td>
 841 <td rowspan="2" width="40%" align="right"> <a accesskey="n" href="dh-manual.html">10. DHAT: a dynamic heap analysis tool &gt;&gt;</a>
 842 </td>
 843 </tr>
 844 <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr>
 845 </table>
 846 </div>
 847 </body>
 848 </html>