Fix warnings in StgCmmGran

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

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 8a7bafd..94995b3 100644 (file)
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -130,6 +130,35 @@
          own signal handlers.</para>
        </listitem>
      </varlistentry>
+
+     <varlistentry>
+       <term><option>-xm<replaceable>address</replaceable></option>
+       <indexterm><primary><option>-xm</option></primary><secondary>RTS
+       option</secondary></indexterm></term>
+       <listitem>
+         <para>
+           WARNING: this option is for working around memory
+           allocation problems only.  Do not use unless GHCi fails
+           with a message like &ldquo;<literal>failed to mmap() memory below 2Gb</literal>&rdquo;.  If you need to use this option to get GHCi working
+           on your machine, please file a bug.
+         </para>
+         
+         <para>
+           On 64-bit machines, the RTS needs to allocate memory in the
+           low 2Gb of the address space.  Support for this across
+           different operating systems is patchy, and sometimes fails.
+           This option is there to give the RTS a hint about where it
+           should be able to allocate memory in the low 2Gb of the
+           address space.  For example, <literal>+RTS -xm20000000
+           -RTS</literal> would hint that the RTS should allocate
+           starting at the 0.5Gb mark.  The default is to use the OS's
+           built-in support for allocating memory in the low 2Gb if
+           available (e.g. <literal>mmap</literal>
+           with <literal>MAP_32BIT</literal> on Linux), or
+           otherwise <literal>-xm40000000</literal>.
+         </para>
+       </listitem>
+     </varlistentry>
     </variablelist>
   </sect2>
 
@@ -448,6 +477,10 @@
           <option>-S</option><optional><replaceable>file</replaceable></optional>
           <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
+       <term>
+          <option>--machine-readable</option>
+          <indexterm><primary><option>--machine-readable</option></primary><secondary>RTS option</secondary></indexterm>
+        </term>
        <listitem>
          <para>These options produce runtime-system statistics, such
          as the amount of time spent executing the program and in the
@@ -514,6 +547,27 @@
     </itemizedlist>
 
     <para>
+        You can also get this in a more future-proof, machine readable
+        format, with <literal>-t --machine-readable</literal>:
+    </para>
+
+<programlisting>
+ [("bytes allocated", "36169392")
+ ,("num_GCs", "69")
+ ,("average_bytes_used", "603392")
+ ,("max_bytes_used", "1065272")
+ ,("num_byte_usage_samples", "2")
+ ,("peak_megabytes_allocated", "3")
+ ,("init_cpu_seconds", "0.00")
+ ,("init_wall_seconds", "0.00")
+ ,("mutator_cpu_seconds", "0.02")
+ ,("mutator_wall_seconds", "0.02")
+ ,("GC_cpu_seconds", "0.07")
+ ,("GC_wall_seconds", "0.07")
+ ]
+</programlisting>
+
+    <para>
         If you use the <literal>-s</literal> flag then, when your
         program finishes, you will see something like this (the exact
         details will vary depending on what sort of RTS you have, e.g.
@@ -531,6 +585,8 @@
   Generation 0:    67 collections,     0 parallel,  0.04s,  0.03s elapsed
   Generation 1:     2 collections,     0 parallel,  0.03s,  0.04s elapsed
 
+  SPARKS: 359207 (557 converted, 149591 pruned)
+
   INIT  time    0.00s  (  0.00s elapsed)
   MUT   time    0.01s  (  0.02s elapsed)
   GC    time    0.07s  (  0.07s elapsed)
@@ -589,6 +645,17 @@
         </para>
       </listitem>
       <listitem>
+        <para>The <literal>SPARKS</literal> statistic refers to the
+          use of <literal>Control.Parallel.par</literal> and related
+          functionality in the program.  Each spark represents a call
+          to <literal>par</literal>; a spark is "converted" when it is
+          executed in parallel; and a spark is "pruned" when it is
+          found to be already evaluated and is discarded from the pool
+          by the garbage collector.  Any remaining sparks are
+          discarded at the end of execution, so "converted" plus
+          "pruned" does not necessarily add up to the total.</para>
+      </listitem>
+      <listitem>
         <para>
         Next there is the CPU time and wall clock time elapsedm broken
         down by what the runtiem system was doing at the time.