X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fprofiling.xml;h=a88c8bbf4c7596749c0eb2c1ccbbaa3466aa079f;hb=0ee7214a53526ffe44caefd0bd78371179e67910;hp=f3529a5f2f2dff1ef63996e72f039a47464e5ebc;hpb=c03e133e8f0c200133c27681aa125fdd0b9e1dec;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/profiling.xml b/ghc/docs/users_guide/profiling.xml
index f3529a5..a88c8bb 100644
--- a/ghc/docs/users_guide/profiling.xml
+++ b/ghc/docs/users_guide/profiling.xml
@@ -898,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>