floating-point fix for x86_64

[ghc-hetmet.git] / ghc / docs / users_guide / profiling.xml

diff --git a/ghc/docs/users_guide/profiling.xml b/ghc/docs/users_guide/profiling.xml
index 3c75ad0..a88c8bb 100644 (file)
--- a/ghc/docs/users_guide/profiling.xml
+++ b/ghc/docs/users_guide/profiling.xml
@@ -769,11 +769,13 @@ x = nfib 25
       <para>In particular, constructors are <emphasis>not</emphasis>
       retainers.</para>
 
-      <para>An object A is retained by an object B if object A can be
-      reached by recursively following pointers starting from object
-      B but not meeting any other retainers on the way.  Each object
-      has one or more retainers, collectively called its
-      <firstterm>retainer set</firstterm>.</para>
+      <para>An object B retains object A if (i) B is a retainer object and
+     (ii) object A can be reached by recursively following pointers
+     starting from object B, but not meeting any other retainer
+     objects on the way. Each live object is retained by one or more
+     retainer objects, collectively called its retainer set, or its
+      <firstterm>retainer set</firstterm>, or its
+      <firstterm>retainers</firstterm>.</para>
 
       <para>When retainer profiling is requested by giving the program
       the <option>-hr</option> option, a graph is generated which is
@@ -896,9 +898,53 @@ x = nfib 25
       information simultaneously.</para>
     </sect2>
 
+    <sect2 id="mem-residency">
+      <title>Actual memory residency</title>
 
+      <para>How does the heap residency reported by the heap profiler relate to
+       the actual memory residency of your program when you run it?  You might
+       see a large discrepancy between the residency reported by the heap
+       profiler, and the residency reported by tools on your system
+       (eg. <literal>ps</literal> or <literal>top</literal> on Unix, or the
+       Task Manager on Windows).  There are several reasons for this:</para>
 
+      <itemizedlist>
+       <listitem>
+         <para>There is an overhead of profiling itself, which is subtracted
+           from the residency figures by the profiler.  This overhead goes
+           away when compiling without profiling support, of course.  The
+           space overhead is currently 2 extra
+           words per heap object, which probably results in
+           about a 30% overhead.</para>
+       </listitem>
 
+       <listitem>
+         <para>Garbage collection requires more memory than the actual
+           residency.  The factor depends on the kind of garbage collection
+           algorithm in use:  a major GC in the standard
+           generation copying collector will usually require 3L bytes of
+           memory, where L is the amount of live data.  This is because by
+           default (see the <option>+RTS -F</option> option) we allow the old
+           generation to grow to twice its size (2L) before collecting it, and
+           we require additionally L bytes to copy the live data into.  When
+           using compacting collection (see the <option>+RTS -c</option>
+           option), this is reduced to 2L, and can further be reduced by
+           tweaking the <option>-F</option> option.  Also add the size of the
+           allocation area (currently a fixed 512Kb).</para>
+       </listitem>
+
+       <listitem>
+         <para>The stack isn't counted in the heap profile by default.  See the
+    <option>+RTS -xt</option> option.</para>
+       </listitem>
+
+       <listitem>
+         <para>The program text itself, the C stack, any non-heap data (eg. data
+           allocated by foreign libraries, and data allocated by the RTS), and
+           <literal>mmap()</literal>'d memory are not counted in the heap profile.</para>
+       </listitem>
+      </itemizedlist>
+    </sect2>
 
   </sect1>
 
@@ -915,14 +961,12 @@ x = nfib 25
       </footnote></para>
 
     <para>To run <command>ghcprof</command>, you need
-    <productname>daVinci</productname> installed, which can be
+    <productname>uDraw(Graph)</productname> installed, which can be
     obtained from <ulink
-    url="http://www.informatik.uni-bremen.de/daVinci/"><citetitle>The Graph
-    Visualisation Tool daVinci</citetitle></ulink>.  Install one of
+    url="http://www.informatik.uni-bremen.de/uDrawGraph/en/uDrawGraph/uDrawGraph.html"><citetitle>uDraw(Graph)</citetitle></ulink>.  Install one of
     the binary
-    distributions<footnote><para><productname>daVinci</productname> is
-    sadly not open-source :-(.</para></footnote>, and set your
-    <envar>DAVINCIHOME</envar> environment variable to point to the
+    distributions, and set your
+    <envar>UDG_HOME</envar> environment variable to point to the
     installation directory.</para>
 
     <para><command>ghcprof</command> uses an XML-based profiling log