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