|
From: <sv...@va...> - 2019-04-16 17:06:59
|
Author: sewardj
Date: Tue Apr 16 17:58:50 2019
New Revision: 536
Log:
Update HTML docs for 3.15.0.
Modified:
trunk/docs/manual/FAQ.html
trunk/docs/manual/QuickStart.html
trunk/docs/manual/bbv-manual.html
trunk/docs/manual/cg-manual.html
trunk/docs/manual/cl-format.html
trunk/docs/manual/cl-manual.html
trunk/docs/manual/design-impl.html
trunk/docs/manual/dh-manual.html
trunk/docs/manual/dist.authors.html
trunk/docs/manual/dist.html
trunk/docs/manual/dist.news.html
trunk/docs/manual/dist.news.old.html
trunk/docs/manual/dist.readme-android.html
trunk/docs/manual/dist.readme-developers.html
trunk/docs/manual/dist.readme-missing.html
trunk/docs/manual/dist.readme-packagers.html
trunk/docs/manual/dist.readme-s390.html
trunk/docs/manual/dist.readme.html
trunk/docs/manual/drd-manual.html
trunk/docs/manual/faq.html
trunk/docs/manual/hg-manual.html
trunk/docs/manual/index.html
trunk/docs/manual/license.gfdl.html
trunk/docs/manual/license.gpl.html
trunk/docs/manual/licenses.html
trunk/docs/manual/lk-manual.html
trunk/docs/manual/manual-core-adv.html
trunk/docs/manual/manual-core.html
trunk/docs/manual/manual-intro.html
trunk/docs/manual/manual-writing-tools.html
trunk/docs/manual/manual.html
trunk/docs/manual/mc-manual.html
trunk/docs/manual/ms-manual.html
trunk/docs/manual/nl-manual.html
trunk/docs/manual/quick-start.html
trunk/docs/manual/sg-manual.html
trunk/docs/manual/tech-docs.html
Modified: trunk/docs/manual/FAQ.html
==============================================================================
--- trunk/docs/manual/FAQ.html (original)
+++ trunk/docs/manual/FAQ.html Tue Apr 16 17:58:50 2019
@@ -3,15 +3,15 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Valgrind FAQ</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="index.html" title="Valgrind Documentation">
-<link rel="prev" href="nl-manual.html" title="14. Nulgrind: the minimal Valgrind tool">
+<link rel="prev" href="bbv-manual.html" title="14. BBV: an experimental basic block vector generation tool">
<link rel="next" href="faq.html" title="Valgrind Frequently Asked Questions">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
-<td width="22px" align="center" valign="middle"><a accesskey="p" href="nl-manual.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
+<td width="22px" align="center" valign="middle"><a accesskey="p" href="bbv-manual.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
<td width="25px" align="center" valign="middle"><a accesskey="u" href="index.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td>
<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>
<th align="center" valign="middle">Valgrind Documentation</th>
@@ -22,10 +22,10 @@
<div>
<div><h1 class="title">
<a name="FAQ"></a>Valgrind FAQ</h1></div>
-<div><p class="releaseinfo">Release 3.14.0 9 October 2018</p></div>
-<div><p class="copyright">Copyright © 2000-2018 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
+<div><p class="releaseinfo">Release 3.15.0 12 April 2019</p></div>
+<div><p class="copyright">Copyright © 2000-2019 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
<div><div class="legalnotice">
-<a name="idm139771388424960"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
+<a name="idm139863058141824"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
</div></div>
</div>
<hr>
@@ -39,7 +39,7 @@
<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
<tr>
<td rowspan="2" width="40%" align="left">
-<a accesskey="p" href="nl-manual.html"><< 14. Nulgrind: the minimal Valgrind tool</a> </td>
+<a accesskey="p" href="bbv-manual.html"><< 14. BBV: an experimental basic block vector generation tool</a> </td>
<td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td>
<td rowspan="2" width="40%" align="right"> <a accesskey="n" href="faq.html">Valgrind Frequently Asked Questions >></a>
</td>
Modified: trunk/docs/manual/QuickStart.html
==============================================================================
--- trunk/docs/manual/QuickStart.html (original)
+++ trunk/docs/manual/QuickStart.html Tue Apr 16 17:58:50 2019
@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>The Valgrind Quick Start Guide</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="index.html" title="Valgrind Documentation">
<link rel="prev" href="index.html" title="Valgrind Documentation">
@@ -22,10 +22,10 @@
<div>
<div><h1 class="title">
<a name="QuickStart"></a>The Valgrind Quick Start Guide</h1></div>
-<div><p class="releaseinfo">Release 3.14.0 9 October 2018</p></div>
-<div><p class="copyright">Copyright © 2000-2018 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
+<div><p class="releaseinfo">Release 3.15.0 12 April 2019</p></div>
+<div><p class="copyright">Copyright © 2000-2019 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
<div><div class="legalnotice">
-<a name="idm139771388209664"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
+<a name="idm139863065998256"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
</div></div>
</div>
<hr>
Modified: trunk/docs/manual/bbv-manual.html
==============================================================================
--- trunk/docs/manual/bbv-manual.html (original)
+++ trunk/docs/manual/bbv-manual.html Tue Apr 16 17:58:50 2019
@@ -1,13 +1,13 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>12. BBV: an experimental basic block vector generation tool</title>
+<title>14. BBV: an experimental basic block vector generation tool</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
-<link rel="prev" href="sg-manual.html" title="11. SGCheck: an experimental stack and global array overrun detector">
-<link rel="next" href="lk-manual.html" title="13. Lackey: an example tool">
+<link rel="prev" href="sg-manual.html" title="13. SGCheck: an experimental stack and global array overrun detector">
+<link rel="next" href="FAQ.html" title="Valgrind FAQ">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
@@ -15,22 +15,22 @@
<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>
<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>
<th align="center" valign="middle">Valgrind User Manual</th>
-<td width="22px" align="center" valign="middle"><a accesskey="n" href="lk-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
+<td width="22px" align="center" valign="middle"><a accesskey="n" href="FAQ.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
-<a name="bbv-manual"></a>12. BBV: an experimental basic block vector generation tool</h1></div></div></div>
+<a name="bbv-manual"></a>14. BBV: an experimental basic block vector generation tool</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.overview">12.1. Overview</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.quickstart">12.2. Using Basic Block Vectors to create SimPoints</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.usage">12.3. BBV Command-line Options</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.fileformat">12.4. Basic Block Vector File Format</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.implementation">12.5. Implementation</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.threadsupport">12.6. Threaded Executable Support</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.validation">12.7. Validation</a></span></dt>
-<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.performance">12.8. Performance</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.overview">14.1. Overview</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.quickstart">14.2. Using Basic Block Vectors to create SimPoints</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.usage">14.3. BBV Command-line Options</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.fileformat">14.4. Basic Block Vector File Format</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.implementation">14.5. Implementation</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.threadsupport">14.6. Threaded Executable Support</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.validation">14.7. Validation</a></span></dt>
+<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.performance">14.8. Performance</a></span></dt>
</dl>
</div>
<p>To use this tool, you must specify
@@ -38,7 +38,7 @@
command line.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.overview"></a>12.1. Overview</h2></div></div></div>
+<a name="bbv-manual.overview"></a>14.1. Overview</h2></div></div></div>
<p>
A basic block is a linear section of code with one entry point and one exit
point. A <span class="emphasis"><em>basic block vector</em></span> (BBV) is a list of all
@@ -76,7 +76,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.quickstart"></a>12.2. Using Basic Block Vectors to create SimPoints</h2></div></div></div>
+<a name="bbv-manual.quickstart"></a>14.2. Using Basic Block Vectors to create SimPoints</h2></div></div></div>
<p>
To quickly create a basic block vector file, you will call Valgrind
like this:
@@ -133,7 +133,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.usage"></a>12.3. BBV Command-line Options</h2></div></div></div>
+<a name="bbv-manual.usage"></a>14.3. BBV Command-line Options</h2></div></div></div>
<p> BBV-specific command-line options are:</p>
<div class="variablelist">
<a name="bbv.opts.list"></a><dl class="variablelist">
@@ -200,7 +200,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.fileformat"></a>12.4. Basic Block Vector File Format</h2></div></div></div>
+<a name="bbv-manual.fileformat"></a>14.4. Basic Block Vector File Format</h2></div></div></div>
<p>
The Basic Block Vector is dumped at fixed intervals. This
is commonly done every 100 million instructions; the
@@ -241,7 +241,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.implementation"></a>12.5. Implementation</h2></div></div></div>
+<a name="bbv-manual.implementation"></a>14.5. Implementation</h2></div></div></div>
<p>
Valgrind provides all of the information necessary to create
BBV files. In the current implementation, all instructions
@@ -310,7 +310,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.threadsupport"></a>12.6. Threaded Executable Support</h2></div></div></div>
+<a name="bbv-manual.threadsupport"></a>14.6. Threaded Executable Support</h2></div></div></div>
<p>
BBV supports threaded programs. When a program has multiple threads,
an additional basic block vector file is created for each thread (each
@@ -328,7 +328,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.validation"></a>12.7. Validation</h2></div></div></div>
+<a name="bbv-manual.validation"></a>14.7. Validation</h2></div></div></div>
<p>
BBV has been tested on x86, amd64, and ppc32 platforms.
An earlier version of BBV was tested in detail using
@@ -340,7 +340,7 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bbv-manual.performance"></a>12.8. Performance</h2></div></div></div>
+<a name="bbv-manual.performance"></a>14.8. Performance</h2></div></div></div>
<p>
Using this program slows down execution by roughly a factor of 40
over native execution. This varies depending on the machine
@@ -354,9 +354,9 @@
<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
<tr>
<td rowspan="2" width="40%" align="left">
-<a accesskey="p" href="sg-manual.html"><< 11. SGCheck: an experimental stack and global array overrun detector</a> </td>
+<a accesskey="p" href="sg-manual.html"><< 13. SGCheck: an experimental stack and global array overrun detector</a> </td>
<td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td>
-<td rowspan="2" width="40%" align="right"> <a accesskey="n" href="lk-manual.html">13. Lackey: an example tool >></a>
+<td rowspan="2" width="40%" align="right"> <a accesskey="n" href="FAQ.html">Valgrind FAQ >></a>
</td>
</tr>
<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr>
Modified: trunk/docs/manual/cg-manual.html
==============================================================================
--- trunk/docs/manual/cg-manual.html (original)
+++ trunk/docs/manual/cg-manual.html Tue Apr 16 17:58:50 2019
@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>5. Cachegrind: a cache and branch-prediction profiler</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="mc-manual.html" title="4. Memcheck: a memory error detector">
@@ -758,6 +758,12 @@
<p><code class="option">--sort=DLmr:1,DLmw:1</code></p>
</dd>
<dt><span class="term">
+ <code class="option">--show-percs=<no|yes> [default: no] </code>
+ </span></dt>
+<dd><p>When enabled, a percentage is printed next to all event counts.
+ This helps gauge the relative importance of each function and line.
+ </p></dd>
+<dt><span class="term">
<code class="option">--auto=<no|yes> [default: no] </code>
</span></dt>
<dd><p>When enabled, automatically annotates every file that
Modified: trunk/docs/manual/cl-format.html
==============================================================================
--- trunk/docs/manual/cl-format.html (original)
+++ trunk/docs/manual/cl-format.html Tue Apr 16 17:58:50 2019
@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>3. Callgrind Format Specification</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="tech-docs.html" title="Valgrind Technical Documentation">
<link rel="prev" href="manual-writing-tools.html" title="2. Writing a New Valgrind Tool">
Modified: trunk/docs/manual/cl-manual.html
==============================================================================
--- trunk/docs/manual/cl-manual.html (original)
+++ trunk/docs/manual/cl-manual.html Tue Apr 16 17:58:50 2019
@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>6. Callgrind: a call-graph generating cache and branch prediction profiler</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="cg-manual.html" title="5. Cachegrind: a cache and branch-prediction profiler">
@@ -1038,18 +1038,34 @@
</span></dt>
<dd><p>Only show figures for events A,B,C.</p></dd>
<dt><span class="term">
+ <code class="option">--threshold=<0--100> [default: 99%] </code>
+ </span></dt>
+<dd>
+<p>Percentage of counts (of primary sort event) we are
+ interested in.</p>
+<p>callgrind_annotate stops printing functions when the sum
+ of the cost percentage of the printed functions is bigger or equal
+ to the given threshold percentage.</p>
+</dd>
+<dt><span class="term">
<code class="option">--sort=A,B,C</code>
</span></dt>
<dd>
<p>Sort columns by events A,B,C [event column order].</p>
<p>Optionally, each event is followed by a : and a threshold,
to specify different thresholds depending on the event.</p>
+<p>callgrind_annotate stops printing functions when the sum
+ of the cost percentage of the printed functions for all the events
+ is bigger or equal to the given event threshold percentages.</p>
+<p>When one or more thresholds are given via this option,
+ the value of <code class="option">--threshold</code> is ignored.</p>
</dd>
<dt><span class="term">
- <code class="option">--threshold=<0--100> [default: 99%] </code>
+ <code class="option">--show-percs=<no|yes> [default: no] </code>
</span></dt>
-<dd><p>Percentage of counts (of primary sort event) we are
- interested in.</p></dd>
+<dd><p>When enabled, a percentage is printed next to all event counts.
+ This helps gauge the relative importance of each function and line.
+ </p></dd>
<dt><span class="term">
<code class="option">--auto=<yes|no> [default: no] </code>
</span></dt>
Modified: trunk/docs/manual/design-impl.html
==============================================================================
--- trunk/docs/manual/design-impl.html (original)
+++ trunk/docs/manual/design-impl.html Tue Apr 16 17:58:50 2019
@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>1. The Design and Implementation of Valgrind</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="tech-docs.html" title="Valgrind Technical Documentation">
<link rel="prev" href="tech-docs.html" title="Valgrind Technical Documentation">
Modified: trunk/docs/manual/dh-manual.html
==============================================================================
--- trunk/docs/manual/dh-manual.html (original)
+++ trunk/docs/manual/dh-manual.html Tue Apr 16 17:58:50 2019
@@ -3,11 +3,11 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>10. DHAT: a dynamic heap analysis tool</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
-<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="ms-manual.html" title="9. Massif: a heap profiler">
-<link rel="next" href="sg-manual.html" title="11. SGCheck: an experimental stack and global array overrun detector">
+<link rel="next" href="lk-manual.html" title="11. Lackey: an example tool">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
@@ -15,7 +15,7 @@
<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>
<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>
<th align="center" valign="middle">Valgrind User Manual</th>
-<td width="22px" align="center" valign="middle"><a accesskey="n" href="sg-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
+<td width="22px" align="center" valign="middle"><a accesskey="n" href="lk-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
@@ -24,43 +24,34 @@
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="sect1"><a href="dh-manual.html#dh-manual.overview">10.1. Overview</a></span></dt>
-<dt><span class="sect1"><a href="dh-manual.html#dh-manual.understanding">10.2. Understanding DHAT's output</a></span></dt>
+<dt><span class="sect1"><a href="dh-manual.html#dh-manual.profile">10.2. Using DHAT</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="dh-manual.html#idm139771384591744">10.2.1. Interpreting the max-live, tot-alloc and deaths fields</a></span></dt>
-<dt><span class="sect2"><a href="dh-manual.html#idm139771384048256">10.2.2. Interpreting the acc-ratios fields</a></span></dt>
-<dt><span class="sect2"><a href="dh-manual.html#idm139771379392032">10.2.3. Interpreting "Aggregated access counts by offset" data</a></span></dt>
+<dt><span class="sect2"><a href="dh-manual.html#dh-manual.running-DHAT">10.2.1. Running DHAT</a></span></dt>
+<dt><span class="sect2"><a href="dh-manual.html#dh-manual.outputfile">10.2.2. Output File</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="dh-manual.html#dh-manual.options">10.3. DHAT Command-line Options</a></span></dt>
+<dt><span class="sect1"><a href="dh-manual.html#dh-manual.viewer">10.3. DHAT's Viewer</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="dh-manual.html#idm139863057826080">10.3.1. The Output Header</a></span></dt>
+<dt><span class="sect2"><a href="dh-manual.html#idm139863060545344">10.3.2. The AP Tree</a></span></dt>
+<dt><span class="sect2"><a href="dh-manual.html#idm139863065431680">10.3.3. The Output Footer</a></span></dt>
+<dt><span class="sect2"><a href="dh-manual.html#idm139863065428528">10.3.4. Sort Metrics</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="dh-manual.html#dh-manual.options">10.4. DHAT Command-line Options</a></span></dt>
</dl>
</div>
<p>To use this tool, you must specify
-<code class="option">--tool=exp-dhat</code> on the Valgrind
-command line.</p>
+<code class="option">--tool=dhat</code> on the Valgrind command line.</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="dh-manual.overview"></a>10.1. Overview</h2></div></div></div>
<p>DHAT is a tool for examining how programs use their heap
allocations.</p>
<p>It tracks the allocated blocks, and inspects every memory access
-to find which block, if any, it is to. The following data is
-collected and presented per allocation point (allocation
-stack):</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>Total allocation (number of bytes and
- blocks)</p></li>
-<li class="listitem"><p>maximum live volume (number of bytes and
- blocks)</p></li>
-<li class="listitem"><p>average block lifetime (number of instructions
- between allocation and freeing)</p></li>
-<li class="listitem"><p>average number of reads and writes to each byte in
- the block ("access ratios")</p></li>
-<li class="listitem"><p>for allocation points which always allocate blocks
- only of one size, and that size is 4096 bytes or less: counts
- showing how often each byte offset inside the block is
- accessed.</p></li>
-</ul></div>
-<p>Using these statistics it is possible to identify allocation
-points with the following characteristics:</p>
+to find which block, if any, it is to. It presents, on an allocation point
+basis, information about these blocks such as sizes, lifetimes, numbers of
+reads and writes, and read and write patterns.</p>
+<p>Using this information it is possible to identify allocation points with
+the following characteristics:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>potential process-lifetime leaks: blocks allocated
by the point just accumulate, and are freed only at the end of the
@@ -78,273 +69,463 @@
</ul></div>
<p>As with the Massif heap profiler, DHAT measures program progress
by counting instructions, and so presents all age/time related figures
-as instruction counts. This sounds a little odd at first, but it
+as instruction counts. This sounds a little odd at first, but it
makes runs repeatable in a way which is not possible if CPU time is
used.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="dh-manual.understanding"></a>10.2. Understanding DHAT's output</h2></div></div></div>
-<p>DHAT provides a lot of useful information on dynamic heap usage.
-Most of the art of using it is in interpretation of the resulting
-numbers. That is best illustrated via a set of examples.</p>
+<a name="dh-manual.profile"></a>10.2. Using DHAT</h2></div></div></div>
+<p>First off, as for normal Valgrind use, you probably want to compile with
+debugging info (the <code class="option">-g</code> option). But by contrast with normal
+Valgrind use, you probably do want to turn optimisation on, since you should
+profile your program as it will be normally run.</p>
+<p>Second, you need to run your program under DHAT to gather the profiling
+information. You might need to reduce the <code class="option">--num-callers</code> value
+to get reasonably-sized output files, especially if you are profiling a large
+program; some trial and error might be needed to find a good value.</p>
+<p>Finally, you need to use DHAT's viewer (in a web browser) to get a
+detailed presentation of that information.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="idm139771384591744"></a>10.2.1. Interpreting the max-live, tot-alloc and deaths fields</h3></div></div></div>
-<div class="sect3"><div class="titlepage"><div><div><h4 class="title">
-<a name="idm139771384591040"></a>10.2.1.1. A simple example</h4></div></div></div></div>
+<a name="dh-manual.running-DHAT"></a>10.2.1. Running DHAT</h3></div></div></div>
+<p>To run DHAT on a program <code class="filename">prog</code>, run:</p>
<pre class="screen">
- ======== SUMMARY STATISTICS ========
+valgrind --tool=dhat prog
+</pre>
+<p>The program will execute (slowly). Upon completion, summary statistics
+that look like this will be printed:</p>
+<pre class="programlisting">
+==11514== Total: 823,849,731 bytes in 3,929,133 blocks
+==11514== At t-gmax: 133,485,082 bytes in 436,521 blocks
+==11514== At t-end: 258,002 bytes in 2,129 blocks
+==11514== Reads: 2,807,182,810 bytes
+==11514== Writes: 1,149,617,086 bytes
+</pre>
+<p>The first line shows how many heap blocks and bytes were allocated over
+the entire execution.</p>
+<p>The second line shows how many heap blocks and bytes were alive at
+<code class="computeroutput">t-gmax</code>, i.e. the time when the heap size
+reached its global maximum (as measured in bytes).</p>
+<p>The third line shows how many heap blocks and bytes were alive at
+<code class="computeroutput">t-end</code>, i.e. the end of execution. In other
+words, how many blocks and bytes were not explicitly freed. </p>
+<p>The fourth and fifth lines show how many bytes within heap blocks were
+read and written during the entire execution. </p>
+<p>These lines are moderately interesting at best. More useful information
+can be seen with DHAT's viewer.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="dh-manual.outputfile"></a>10.2.2. Output File</h3></div></div></div>
+<p>As well as printing summary information, DHAT also writes more detailed
+profiling information to a file. By default this file is named
+<code class="filename">dhat.out.<pid></code> (where
+<code class="filename"><pid></code> is the program's process ID), but its name can
+be changed with the <code class="option">--dhat-out-file</code> option. This file is JSON,
+and intended to be viewed by DHAT's viewer, which is described in the next
+section.</p>
+<p>The default <code class="computeroutput">.<pid></code> suffix on the
+output file name serves two purposes. Firstly, it means you don't have to
+rename old log files that you don't want to overwrite. Secondly, and more
+importantly, it allows correct profiling with the
+<code class="option">--trace-children=yes</code> option of programs that spawn child
+processes.</p>
+<p>The output file can be big, many megabytes for large applications
+built with full debugging information.</p>
+</div>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="dh-manual.viewer"></a>10.3. DHAT's Viewer</h2></div></div></div>
+<p>DHAT's viewer can be run in a web browser by loading the file
+<code class="computeroutput">dh_view.html</code>. Use the "Load" button to choose
+a DHAT output file to view.</p>
+<p>If loading takes a long time, it might be worth re-running DHAT with a
+smaller <code class="option">--num-callers</code> value to reduce the stack depths,
+because this can significantly reduce the size of DHAT's output files.</p>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="idm139863057826080"></a>10.3.1. The Output Header</h3></div></div></div>
+<p>The first part of the output shows the program command and process ID.
+For example:</p>
+<pre class="programlisting">
+Invocation {
+ Command: /home/njn/moz/rust0/build/x86_64-unknown-linux-gnu/stage2/bin/rustc --crate-name tuple_stress src/main.rs
+ PID: 18816
+}
+</pre>
+<p>The second part of the output shows the
+<code class="computeroutput">t-gmax</code> and
+<code class="computeroutput">t-end</code> values again. For example:</p>
+<pre class="programlisting">
+Times {
+ t-gmax: 8,138,210,673 instrs (86.92% of program duration)
+ t-end: 9,362,544,994 instrs
+}
+</pre>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="idm139863060545344"></a>10.3.2. The AP Tree</h3></div></div></div>
+<p>The third part of the output is the largest and most interesting part,
+showing the allocation point (AP) tree.</p>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="idm139863056771648"></a>10.3.2.1. Structure</h4></div></div></div>
- guest_insns: 1,045,339,534
- [...]
- max-live: 63,490 in 984 blocks
- tot-alloc: 1,904,700 in 29,520 blocks (avg size 64.52)
- deaths: 29,520, at avg age 22,227,424
- acc-ratios: 6.37 rd, 1.14 wr (12,141,526 b-read, 2,174,460 b-written)
- at 0x4C275B8: malloc (vg_replace_malloc.c:236)
- by 0x40350E: tcc_malloc (tinycc.c:6712)
- by 0x404580: tok_alloc_new (tinycc.c:7151)
- by 0x40870A: next_nomacro1 (tinycc.c:9305)
-</pre>
-<p>Over the entire run of the program, this stack (allocation
-point) allocated 29,520 blocks in total, containing 1,904,700 bytes in
-total. By looking at the max-live data, we see that not many blocks
-were simultaneously live, though: at the peak, there were 63,490
-allocated bytes in 984 blocks. This tells us that the program is
-steadily freeing such blocks as it runs, rather than hanging on to all
-of them until the end and freeing them all.</p>
-<p>The deaths entry tells us that 29,520 blocks allocated by this stack
-died (were freed) during the run of the program. Since 29,520 is
-also the number of blocks allocated in total, that tells us that
-all allocated blocks were freed by the end of the program.</p>
-<p>It also tells us that the average age at death was 22,227,424
-instructions. From the summary statistics we see that the program ran
-for 1,045,339,534 instructions, and so the average age at death is
-about 2% of the program's total run time.</p>
-<div class="sect3"><div class="titlepage"><div><div><h4 class="title">
-<a name="idm139771383650416"></a>10.2.1.2. Example of a potential process-lifetime leak</h4></div></div></div></div>
-<p>This next example (from a different program than the above)
-shows a potential process lifetime leak. A process lifetime leak
-occurs when a program keeps allocating data, but only frees the
-data just before it exits. Hence the program's heap grows constantly
-in size, yet Memcheck reports no leak, because the program has
-freed up everything at exit. This is particularly a hazard for
-long running programs.</p>
-<pre class="screen">
- ======== SUMMARY STATISTICS ========
-
- guest_insns: 418,901,537
- [...]
- max-live: 32,512 in 254 blocks
- tot-alloc: 32,512 in 254 blocks (avg size 128.00)
- deaths: 254, at avg age 300,467,389
- acc-ratios: 0.26 rd, 0.20 wr (8,756 b-read, 6,604 b-written)
- at 0x4C275B8: malloc (vg_replace_malloc.c:236)
- by 0x4C27632: realloc (vg_replace_malloc.c:525)
- by 0x56FF41D: QtFontStyle::pixelSize(unsigned short, bool) (qfontdatabase.cpp:269)
- by 0x5700D69: loadFontConfig() (qfontdatabase_x11.cpp:1146)
-</pre>
-<p>There are two tell-tale signs that this might be a
-process-lifetime leak. Firstly, the max-live and tot-alloc numbers
-are identical. The only way that can happen is if these blocks are
-all allocated and then all deallocated.</p>
-<p>Secondly, the average age at death (300 million insns) is 71% of
-the total program lifetime (419 million insns), hence this is not a
-transient allocation-free spike -- rather, it is spread out over a
-large part of the entire run. One interpretation is, roughly, that
-all 254 blocks were allocated in the first half of the run, held onto
-for the second half, and then freed just before exit.</p>
+The following image shows a screenshot of part of an AP tree. The font is very
+small because this screenshot is intended to demonstrate the high-level
+structure of the tree rather than the details within the text.
+
+<div><img src="images/dh-tree.png"></div>
+<p>Like any tree, it has a root node, leaf nodes, and non-leaf nodes. The
+structure of the tree is shown by the lines connecting nodes. Child nodes are
+beneath their parent and indented one level.</p>
+<p>The sub-trees beneath a non-leaf node can be collapsed or expanded by
+clicking on the node. It is useful to collapse sub-trees that you aren't
+interested in.</p>
+<p>Colours are meaningful, and are intended to ease tree navigation, but the
+information they represent is also present within the text. (This means that
+colour-blind users are not denied any information.)</p>
+<p>Each leaf node is coloured green. Each non-leaf node is coloured blue
+and has a down arrow (<code class="computeroutput">▼</code>) next to it when
+its sub-tree is expanded. Each non-leaf node is coloured yellow and has a
+left arrow (<code class="computeroutput">▶</code>) next to it when its sub-tree
+is collapsed.</p>
+<p>The shade of green, blue or yellow used for a node indicate its
+significance. Darker shades represent greater significance (in terms of bytes
+or blocks).</p>
+<p>Note that the entire output is text, even the arrows and lines connecting
+nodes. This means you can copy and paste any part of the output easily into an
+email, bug report, etc.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="idm139863061768976"></a>10.3.2.2. The Root Node</h4></div></div></div>
+<p>The root node looks like this:</p>
+<pre class="programlisting">
+AP 1/1 (25 children) {
+ Total: 1,355,253,987 bytes (100%, 67,454.81/Minstr) in 5,943,417 blocks (100%, 295.82/Minstr), avg size 228.03 bytes, avg lifetime 3,134,692,250.67 instrs (15.6% of program duration)
+ At t-gmax: 423,930,307 bytes (100%) in 1,575,682 blocks (100%), avg size 269.05 bytes
+ At t-end: 258,002 bytes (100%) in 2,129 blocks (100%), avg size 121.18 bytes
+ Reads: 5,478,606,988 bytes (100%, 272,685.7/Minstr), 4.04/byte
+ Writes: 2,040,294,800 bytes (100%, 101,551.22/Minstr), 1.51/byte
+ Allocated at {
+ #0: [root]
+ }
+}
+</pre>
+<p>The root node covers the entire execution. The information is a superset
+of the information shown when DHAT ran, adding details such as allocation
+rates, average block sizes, block lifetimes, and read and write ratios. The
+next example will explain these in more detail.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="idm139863061765808"></a>10.3.2.3. Interior Nodes</h4></div></div></div>
+<p>AP nodes further down the tree show information about a subset of
+allocations. For example:</p>
+<pre class="programlisting">
+AP 1.1/25 (2 children) {
+ Total: 54,533,440 bytes (4.02%, 2,714.28/Minstr) in 458,839 blocks (7.72%, 22.84/Minstr), avg size 118.85 bytes, avg lifetime 1,127,259,403.64 instrs (5.61% of program duration)
+ At t-gmax: 0 bytes (0%) in 0 blocks (0%), avg size 0 bytes
+ At t-end: 0 bytes (0%) in 0 blocks (0%), avg size 0 bytes
+ Reads: 15,993,012 bytes (0.29%, 796.02/Minstr), 0.29/byte
+ Writes: 20,974,752 bytes (1.03%, 1,043.97/Minstr), 0.38/byte
+ Allocated at {
+ #1: 0x95CACC9: alloc (alloc.rs:72)
+ #2: 0x95CACC9: alloc (alloc.rs:148)
+ #3: 0x95CACC9: reserve_internal<syntax::tokenstream::TokenStream,alloc::alloc::Global> (raw_vec.rs:669)
+ #4: 0x95CACC9: reserve<syntax::tokenstream::TokenStream,alloc::alloc::Global> (raw_vec.rs:492)
+ #5: 0x95CACC9: reserve<syntax::tokenstream::TokenStream> (vec.rs:460)
+ #6: 0x95CACC9: push<syntax::tokenstream::TokenStream> (vec.rs:989)
+ #7: 0x95CACC9: parse_token_trees_until_close_delim (tokentrees.rs:27)
+ #8: 0x95CACC9: syntax::parse::lexer::tokentrees::<impl syntax::parse::lexer::StringReader<'a>>::parse_token_tree (tokentrees.rs:81)
+ }
+}
+</pre>
+<p>The first line indicates the node's position in the tree. The
+<code class="computeroutput">1.1</code> is a unique identifier for the node and
+also says that it is the first child node <code class="computeroutput">1</code>
+(which is the root). The <code class="computeroutput">/25</code> says that it is
+one of 25 children, i.e. it has 24 siblings. The <code class="computeroutput">(2
+children)</code> says that this node node has two children of its
+own.</p>
+<p>Allocations are aggregated by their allocation stack trace. The
+<code class="computeroutput">Allocated at</code> section shows the allocation
+stack trace that is shared by all the blocks covered by this node.</p>
+<p>The <code class="computeroutput">Total</code> line shows that this node
+accounts for 4.02% of all bytes allocated during execution, and 7.72% of all
+blocks. These percentages are useful for comparing the significance of
+different nodes within a single profile; an AP that accounts for 10% of bytes
+allocated is likely to be more interesting than one that accounts for
+2%.</p>
+<p>The <code class="computeroutput">Total</code> line also shows allocation
+rates, measured in bytes and blocks per million instructions. These rates are
+useful for comparing the significance of nodes across profiles made with
+different workloads.</p>
+<p>Finally, the <code class="computeroutput">Total</code> line shows the
+average size and lifetimes of these blocks.</p>
+<p>The <code class="computeroutput">At t-gmax</code> line says shows that no
+blocks from this AP were alive when the global heap peak occurred. In other
+words, these blocks do not contribute at all to the global heap peak.</p>
+<p>The <code class="computeroutput">At t-end</code> line shows that no blocks
+were from this AP were alive at shutdown. In other words, all those blocks were
+explicitly freed before termination.</p>
+<p>The <code class="computeroutput">Reads</code> and
+<code class="computeroutput">Writes</code> lines show how many bytes were read
+within this AP's blocks, the fraction this represents of all heap reads, and
+the read rate. Finally, it shows the read ratio, which is the number of reads
+per byte. In this case the number is 0.29, which is quite low -- if no byte was
+read twice, then only 29% of the allocated bytes, which means that at least 71%
+of the bytes were never read! This suggests that the blocks are being
+underutilized and might be worth optimizing.</p>
+<p>The <code class="computeroutput">Writes</code> lines is similar to the
+<code class="computeroutput">Reads</code> line. In this case, at most 38% of the
+bytes are ever written, and at least 62% of the bytes were never written.
+</p>
+<p>The <code class="computeroutput">Reads</code> and
+<code class="computeroutput">Writes</code> measurements suggest that the blocks
+are being under-utilised and might be worth optimizing. Having said that, this
+kind of under-utilisation is common in data structures that grow, such as
+vectors and hash tables, and isn't always fixable. </p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="idm139863062163264"></a>10.3.2.4. Leaf Nodes</h4></div></div></div>
+<p>This is a leaf node:</p>
+<pre class="programlisting">
+AP 1.1.1.1/2 {
+ Total: 31,460,928 bytes (2.32%, 1,565.9/Minstr) in 262,171 blocks (4.41%, 13.05/Minstr), avg size 120 bytes, avg lifetime 986,406,885.05 instrs (4.91% of program duration)
+ Max: 16,779,136 bytes in 65,543 blocks, avg size 256 bytes
+ At t-gmax: 0 bytes (0%) in 0 blocks (0%), avg size 0 bytes
+ At t-end: 0 bytes (0%) in 0 blocks (0%), avg size 0 bytes
+ Reads: 5,964,704 bytes (0.11%, 296.88/Minstr), 0.19/byte
+ Writes: 10,487,200 bytes (0.51%, 521.98/Minstr), 0.33/byte
+ Allocated at {
+ ^1: 0x95CACC9: alloc (alloc.rs:72)
+ ^2: 0x95CACC9: alloc (alloc.rs:148)
+ ^3: 0x95CACC9: reserve_internal<syntax::tokenstream::TokenStream,alloc::alloc::Global> (raw_vec.rs:669)
+ ^4: 0x95CACC9: reserve<syntax::tokenstream::TokenStream,alloc::alloc::Global> (raw_vec.rs:492)
+ ^5: 0x95CACC9: reserve<syntax::tokenstream::TokenStream> (vec.rs:460)
+ ^6: 0x95CACC9: push<syntax::tokenstream::TokenStream> (vec.rs:989)
+ ^7: 0x95CACC9: parse_token_trees_until_close_delim (tokentrees.rs:27)
+ ^8: 0x95CACC9: syntax::parse::lexer::tokentrees::<impl syntax::parse::lexer::StringReader<'a>>::parse_token_tree (tokentrees.rs:81)
+ ^9: 0x95CAC39: parse_token_trees_until_close_delim (tokentrees.rs:26)
+ ^10: 0x95CAC39: syntax::parse::lexer::tokentrees::<impl syntax::parse::lexer::StringReader<'a>>::parse_token_tree (tokentrees.rs:81)
+ #11: 0x95CAC39: parse_token_trees_until_close_delim (tokentrees.rs:26)
+ #12: 0x95CAC39: syntax::parse::lexer::tokentrees::<impl syntax::parse::lexer::StringReader<'a>>::parse_token_tree (tokentrees.rs:81)
+ }
+}
+</pre>
+<p>The <code class="computeroutput">1.1.1.1/2</code> indicates that this node
+is a great-grandchild of the root; is the first grandchild of the node in the
+previous example; and has no children.</p>
+<p>Leaf nodes contain an additional <code class="computeroutput">Max</code>
+line, indicating the peak memory use for the blocks covered by this AP. (This
+peak may have occurred at a time other than
+<code class="computeroutput">t-gmax</code>.) In this case, 31,460,298 bytes were
+allocated from this AP, but the maximum size alive at once was 16,779,136
+bytes.</p>
+<p>Stack frames that begin with a <code class="computeroutput">^</code> rather
+than a <code class="computeroutput">#</code> are copied from ancestor nodes.
+(In this example, the first 8 frames are identical to those from the node in
+the previous example.) These frames could be found by tracing back through
+ancestor nodes, but that can be annoying, which is why they are duplicated.
+This also means that each node makes complete sense on its own.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="idm139863062107296"></a>10.3.2.5. Access Counts</h4></div></div></div>
+<p>If all blocks covered by an AP node have the same size, an additional
+<code class="computeroutput">Accesses</code> field will be present. It indicates
+how the reads and writes within these blocks were distributed. For
+example:</p>
+<pre class="programlisting">
+Total: 8,388,672 bytes (0.62%, 417.53/Minstr) in 262,146 blocks (4.41%, 13.05/Minstr), avg size 32 bytes, avg lifetime 16,726,078,401.51 instrs (83.25% of program duration)
+At t-gmax: 8,388,672 bytes (1.98%) in 262,146 blocks (16.64%), avg size 32 bytes
+At t-end: 0 bytes (0%) in 0 blocks (0%), avg size 0 bytes
+Reads: 9,109,682 bytes (0.17%, 453.41/Minstr), 1.09/byte
+Writes: 7,340,088 bytes (0.36%, 365.34/Minstr), 0.88/byte
+Accesses: {
+ [ 0] 65547 7 8 4 65529 〃 〃 〃 16 〃 〃 〃 12 〃 〃 〃 〃 〃 〃 〃 〃 〃 〃 〃 65542 〃 〃 〃 - - - -
+}
+</pre>
+<p>Every block covered by this AP was 32 bytes. Within all of those blocks,
+byte 0 was accessed (read or written) 65,547 times, byte 1 was accessed 7
+times, byte 2 was accessed 8 times, and so on.</p>
+<p>The ditto symbol (<code class="computeroutput">〃</code>) means "same access
+count as the previous byte".</p>
+<p>A dash (<code class="computeroutput">-</code>) means "zero". (It is used
+instead of <code class="computeroutput">0</code> because it makes unaccessed
+regions more easily identifiable.)</p>
+<p>The infinity symbol (<code class="computeroutput">∞</code>, not present in
+this example) means "exceeded the maximum tracked count".</p>
+<p>Block layout can often be inferred from counts. For example, these blocks
+probably have four separate byte-sized fields, followed by a four-byte field,
+and so on.</p>
+<p>Access counts can be useful for identifying data alignment holes or other
+layout inefficiencies.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="idm139863062434736"></a>10.3.2.6. Aggregate Nodes</h4></div></div></div>
+<p>The AP tree is very large and many nodes represent tiny numbers of blocks
+and bytes. Therefore, DHAT's viewer aggregates insignificant nodes like
+this:</p>
+<pre class="programlisting">
+AP 1.14.2/2 {
+ Total: 5,175 blocks (0.09%, 0.26/Minstr)
+ Allocated at {
+ [5 insignificant]
+ }
+}
+</pre>
+<p>Much of the detail is stripped away, leaving only basic measurements,
+along with an indication of how many nodes were aggregated together (5 in this
+case).</p>
+</div>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="idm139771384048256"></a>10.2.2. Interpreting the acc-ratios fields</h3></div></div></div>
-<div class="sect3"><div class="titlepage"><div><div><h4 class="title">
-<a name="idm139771384047504"></a>10.2.2.1. A fairly harmless allocation point record</h4></div></div></div></div>
-<pre class="screen">
- max-live: 49,398 in 808 blocks
- tot-alloc: 1,481,940 in 24,240 blocks (avg size 61.13)
- deaths: 24,240, at avg age 34,611,026
- acc-ratios: 2.13 rd, 0.91 wr (3,166,650 b-read, 1,358,820 b-written)
- at 0x4C275B8: malloc (vg_replace_malloc.c:236)
- by 0x40350E: tcc_malloc (tinycc.c:6712)
- by 0x404580: tok_alloc_new (tinycc.c:7151)
- by 0x4046C4: tok_alloc (tinycc.c:7190)
-</pre>
-<p>The acc-ratios field tells us that each byte in the blocks
-allocated here is read an average of 2.13 times before the block is
-deallocated. Given that the blocks have an average age at death of
-34,611,026, that's one read per block per approximately every 15
-million instructions. So from that standpoint the blocks aren't
-"working" very hard.</p>
-<p>More interesting is the write ratio: each byte is written an
-average of 0.91 times. This tells us that some parts of the allocated
-blocks are never written, at least 9% on average. To completely
-initialise the block would require writing each byte at least once,
-and that would give a write ratio of 1.0. The fact that some block
-areas are evidently unused might point to data alignment holes or
-other layout inefficiencies.</p>
-<p>Well, at least all the blocks are freed (24,240 allocations,
-24,240 deaths).</p>
-<p>If all the blocks had been the same size, DHAT would also show
-the access counts by block offset, so we could see where exactly these
-unused areas are. However, that isn't the case: the blocks have
-varying sizes, so DHAT can't perform such an analysis. We can see
-that they must have varying sizes since the average block size, 61.13,
-isn't a whole number.</p>
-<div class="sect3"><div class="titlepage"><div><div><h4 class="title">
-<a name="idm139771394771296"></a>10.2.2.2. A more suspicious looking example</h4></div></div></div></div>
-<pre class="screen">
- max-live: 180,224 in 22 blocks
- tot-alloc: 180,224 in 22 blocks (avg size 8192.00)
- deaths: none (none of these blocks were freed)
- acc-ratios: 0.00 rd, 0.00 wr (0 b-read, 0 b-written)
- at 0x4C275B8: malloc (vg_replace_malloc.c:236)
- by 0x40350E: tcc_malloc (tinycc.c:6712)
- by 0x40369C: __sym_malloc (tinycc.c:6787)
- by 0x403711: sym_malloc (tinycc.c:6805)
-</pre>
-<p>Here, both the read and write access ratios are zero. Hence
-this point is allocating blocks which are never used, neither read nor
-written. Indeed, they are also not freed ("deaths: none") and are
-simply leaked. So, here is 180k of completely useless allocation that
-could be removed.</p>
-<p>Re-running with Memcheck does indeed report the same leak. What
-DHAT can tell us, that Memcheck can't, is that not only are the blocks
-leaked, they are also never used.</p>
-<div class="sect3"><div class="titlepage"><div><div><h4 class="title">
-<a name="idm139771394768272"></a>10.2.2.3. Another suspicious example</h4></div></div></div></div>
-<p>Here's one where blocks are allocated, written to,
-but never read from. We see this immediately from the zero read
-access ratio. They do get freed, though:</p>
-<pre class="screen">
- max-live: 54 in 3 blocks
- tot-alloc: 1,620 in 90 blocks (avg size 18.00)
- deaths: 90, at avg age 34,558,236
- acc-ratios: 0.00 rd, 1.11 wr (0 b-read, 1,800 b-written)
- at 0x4C275B8: malloc (vg_replace_malloc.c:236)
- by 0x40350E: tcc_malloc (tinycc.c:6712)
- by 0x4035BD: tcc_strdup (tinycc.c:6750)
- by 0x41FEBB: tcc_add_sysinclude_path (tinycc.c:20931)
-</pre>
-<p>In the previous two examples, it is easy to see blocks that are
-never written to, or never read from, or some combination of both.
-Unfortunately, in C++ code, the situation is less clear. That's
-because an object's constructor will write to the underlying block,
-and its destructor will read from it. So the block's read and write
-ratios will be non-zero even if the object, once constructed, is never
-used, but only eventually destructed.</p>
-<p>Really, what we want is to measure only memory accesses in
-between the end of an object's construction and the start of its
-destruction. Unfortunately I do not know of a reliable way to
-determine when those transitions are made.</p>
+<a name="idm139863065431680"></a>10.3.3. The Output Footer</h3></div></div></div>
+<p>Below the AP tree is a line like this:</p>
+<pre class="programlisting">
+AP significance threshold: total >= 59,434.17 blocks (1%)
+</pre>
+<p>It shows the function used to determine if an AP node is significant. All
+nodes that don't satisfy this function are aggregated. It is occasionally
+useful if you don't understand why an AP node has been aggregated. The exact
+threshold depends on the sort metric (see below).</p>
+<p>Finally, the bottom of the page shows a legend that explains some of the
+terms, abbreviations and symbols used in the output.</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="idm139771379392032"></a>10.2.3. Interpreting "Aggregated access counts by offset" data</h3></div></div></div>
-<p>For allocation points that always allocate blocks of the same
-size, and which are 4096 bytes or smaller, DHAT counts accesses
-per offset, for example:</p>
-<pre class="screen">
- max-live: 317,408 in 5,668 blocks
- tot-alloc: 317,408 in 5,668 blocks (avg size 56.00)
- deaths: 5,668, at avg age 622,890,597
- acc-ratios: 1.03 rd, 1.28 wr (327,642 b-read, 408,172 b-written)
- at 0x4C275B8: malloc (vg_replace_malloc.c:236)
- by 0x5440C16: QDesignerPropertySheetPrivate::ensureInfo (qhash.h:515)
- by 0x544350B: QDesignerPropertySheet::setVisible (qdesigner_propertysh...)
- by 0x5446232: QDesignerPropertySheet::QDesignerPropertySheet (qdesigne...)
-
- Aggregated access counts by offset:
-
- [ 0] 28782 28782 28782 28782 28782 28782 28782 28782
- [ 8] 20638 20638 20638 20638 0 0 0 0
- [ 16] 22738 22738 22738 22738 22738 22738 22738 22738
- [ 24] 6013 6013 6013 6013 6013 6013 6013 6013
- [ 32] 18883 18883 18883 37422 0 0 0 0
- [ 36] 5668 11915 5668 5668 11336 11336 11336 11336
- [ 48] 6166 6166 6166 6166 0 0 0 0
-</pre>
-<p>This is fairly typical, for C++ code running on a 64-bit
-platform. Here, we have aggregated access statistics for 5668 blocks,
-all of size 56 bytes. Each byte has been accessed at least 5668
-times, except for offsets 12--15, 36--39 and 52--55. These are likely
-to be alignment holes.</p>
-<p>Careful interpretation of the numbers reveals useful information.
-Groups of N consecutive identical numbers that begin at an N-aligned
-offset, for N being 2, 4 or 8, are likely to indicate an N-byte object
-in the structure at that point. For example, the first 32 bytes of
-this object are likely to have the layout</p>
-<pre class="screen">
- [0 ] 64-bit type
- [8 ] 32-bit type
- [12] 32-bit alignment hole
- [16] 64-bit type
- [24] 64-bit type
-</pre>
-<p>As a counterexample, it's also clear that, whatever is at offset 32,
-it is not a 32-bit value. That's because the last number of the group
-(37422) is not the same as the first three (18883 18883 18883).</p>
-<p>This example leads one to enquire (by reading the source code)
-whether the zeroes at 12--15 and 52--55 are alignment holes, and
-whether 48--51 is indeed a 32-bit type. If so, it might be possible
-to place what's at 48--51 at 12--15 instead, which would reduce
-the object size from 56 to 48 bytes.</p>
-<p>Bear in mind that the above inferences are all only "maybes". That's
-because they are based on dynamic data, not static analysis of the
-object layout. For example, the zeroes might not be alignment
-holes, but rather just parts of the structure which were not used
-at all for this particular run. Experience shows that's unlikely
-to be the case, but it could happen.</p>
+<a name="idm139863065428528"></a>10.3.4. Sort Metrics</h3></div></div></div>
+<p>The order in which sub-trees are sorted can be changed via the "Sort
+metric" drop-down menu at the top of DHAT's viewer. Different sort metrics can
+be useful for finding different things. Some sort metrics also incorporate some
+filtering, so that only nodes meeting a particular criteria are shown.</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term">Total (bytes)</span></dt>
+<dd><p>The total number of bytes allocated during the execution.
+ Highly useful for evaluating heap churn, though not quite as useful as
+ "Total (blocks)".
+ </p></dd>
+<dt><span class="term">Total (blocks)</span></dt>
+<dd><p>The total number of blocks allocated during the execution.
+ Highly useful for evaluating heap churn; reducing the number of calls to
+ the allocator can significantly speed up a program. This is the default
+ sort metric.
+ </p></dd>
+<dt><span class="term">Total (blocks), tiny</span></dt>
+<dd><p>Like "Total (blocks)", but shows only very small blocks.
+ Moderately useful, because such blocks are often easy to avoid allocating.
+ </p></dd>
+<dt><span class="term">Total (blocks), short-lived</span></dt>
+<dd><p>Like "Total (blocks)", but shows only very short-lived
+ blocks. Moderately useful, because such blocks are often easy to avoid
+ allocating.
+ </p></dd>
+<dt><span class="term">Total (bytes), zero reads or zero writes</span></dt>
+<dd><p>Like "Total (bytes)", but shows only blocks that are
+ never read or never written to (or both). Highly useful, because such
+ blocks indicate poor use of memory and are often easy to avoid allocating.
+ For example, sometimes a block is allocated and written to but then only
+ read if a condition C is true; in that case, it may be possible to delay
+ creating the block until condition C is true. Alternatively, sometimes
+ blocks are created and never used; such blocks are trivial to remove.
+ </p></dd>
+<dt><span class="term">Total (blocks), zero reads or zero writes</span></dt>
+<dd><p>Like "Total (bytes), zero reads or zero writes" but for
+ blocks. Highly useful.
+ </p></dd>
+<dt><span class="term">Total (bytes), low-access</span></dt>
+<dd><p>Like "Total (bytes)", but shows only blocks that have low
+ numbers of reads or low numbers of writes (or both). Moderately useful,
+ because such blocks indicate poor use of memory.
+ </p></dd>
+<dt><span class="term">Total (blocks), low-access</span></dt>
+<dd><p>Like "Total (bytes), low-access", but for blocks.
+ </p></dd>
+<dt><span class="term">At t-gmax (bytes)</span></dt>
+<dd><p>This shows the breakdown of memory at the point of peak
+ heap memory usage. Highly useful for reducing peak memory usage.
+ </p></dd>
+<dt><span class="term">At t-end (bytes)</span></dt>
+<dd><p>This shows the breakdown of memory at program termination.
+ Highly useful for identifying process-lifetime leaks.
+ </p></dd>
+<dt><span class="term">Reads (bytes)</span></dt>
+<dd><p>The number of bytes read within heap bloc...
[truncated message content] |