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