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