Add +RTS -n<size>: divide the nursery into chunks
[ghc.git] / docs / users_guide / runtime_control.xml
index 9ef32a8..612a441 100644 (file)
 
   <para>To make an executable program, the GHC system compiles your
   code and then links it with a non-trivial runtime system (RTS),
-  which handles storage management, profiling, etc.</para>
+  which handles storage management, thread scheduling, profiling, and
+  so on.</para>
+
+  <para>
+    The RTS has a lot of options to control its behaviour.  For
+    example, you can change the context-switch interval, the default
+    size of the heap, and enable heap profiling.  These options can be
+    passed to the runtime system in a variety of different ways; the
+    next section (<xref linkend="setting-rts-options" />) describes
+    the various methods, and the following sections describe the RTS
+    options themselves.
+  </para>
+
+  <sect2 id="setting-rts-options">
+    <title>Setting RTS options</title>
+    <indexterm><primary>RTS options, setting</primary></indexterm>
 
-  <para>If you use the <literal>-rtsopts</literal> flag when linking,
-  you have some control over the behaviour of the RTS, by giving
-  special command-line arguments to your program.</para>
+    <para>
+      There are four ways to set RTS options:
 
-  <para>When your Haskell program starts up, its RTS extracts
-  command-line arguments bracketed between
-  <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm>
-  and
-  <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm>
-  as its own.  For example:</para>
+      <itemizedlist>
+        <listitem>
+          <para>
+          on the command line between <literal>+RTS ... -RTS</literal>, when running the program
+           (<xref linkend="rts-opts-cmdline" />)
+          </para>
+        </listitem>
+        <listitem>
+          <para>at compile-time, using <option>--with-rtsopts</option>
+            (<xref linkend="rts-opts-compile-time" />)
+          </para>
+        </listitem>
+        <listitem>
+          <para>with the environment variable <envar>GHCRTS</envar>
+          (<xref linkend="rts-options-environment" />)
+          </para>
+        </listitem>
+        <listitem>
+          <para>by overriding &ldquo;hooks&rdquo; in the runtime system
+            (<xref linkend="rts-hooks" />)
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+
+    <sect3 id="rts-opts-cmdline">
+      <title>Setting RTS options on the command line</title>
+
+      <para>
+        If you set the <literal>-rtsopts</literal> flag appropriately
+        when linking (see <xref linkend="options-linker" />), you can
+        give RTS options on the command line when running your
+        program.
+      </para>
+
+      <para>
+        When your Haskell program starts up, the RTS extracts
+        command-line arguments bracketed between
+        <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm>
+        and
+        <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm>
+        as its own.  For example:
+      </para>
 
 <screen>
-% ./a.out -f +RTS -p -S -RTS -h foo bar
+$ ghc prog.hs -rtsopts
+[1 of 1] Compiling Main             ( prog.hs, prog.o )
+Linking prog ...
+$ ./prog -f +RTS -H32m -S -RTS -h foo bar
 </screen>
 
-  <para>The RTS will snaffle <option>-p</option> <option>-S</option>
-  for itself, and the remaining arguments <literal>-f -h foo bar</literal>
-  will be handed to your program if/when it calls
-  <function>System.getArgs</function>.</para>
+        <para>
+          The RTS will
+          snaffle <option>-H32m</option> <option>-S</option> for itself,
+          and the remaining arguments <literal>-f -h foo bar</literal>
+          will be available to your program if/when it calls
+          <function>System.Environment.getArgs</function>.
+        </para>
 
-  <para>No <option>-RTS</option> option is required if the
-  runtime-system options extend to the end of the command line, as in
-  this example:</para>
+        <para>
+          No <option>-RTS</option> option is required if the
+          runtime-system options extend to the end of the command line, as in
+          this example:
+        </para>
 
 <screen>
 % hls -ltr /usr/etc +RTS -A5m
 </screen>
 
-  <para>If you absolutely positively want all the rest of the options
-  in a command line to go to the program (and not the RTS), use a
-  <option>&ndash;&ndash;RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.</para>
-
-  <para>As always, for RTS options that take
-  <replaceable>size</replaceable>s: If the last character of
-  <replaceable>size</replaceable> is a K or k, multiply by 1000; if an
-  M or m, by 1,000,000; if a G or G, by 1,000,000,000.  (And any
-  wraparound in the counters is <emphasis>your</emphasis>
-  fault!)</para>
-
-  <para>Giving a <literal>+RTS -f</literal>
-  <indexterm><primary><option>-f</option></primary><secondary>RTS option</secondary></indexterm> option
-  will print out the RTS options actually available in your program
-  (which vary, depending on how you compiled).</para>
-
-  <para>NOTE: since GHC is itself compiled by GHC, you can change RTS
-  options in the compiler using the normal
-  <literal>+RTS ... -RTS</literal>
-  combination.  eg. to increase the maximum heap
-  size for a compilation to 128M, you would add
-  <literal>+RTS -M128m -RTS</literal>
-  to the command line.</para>
-
-  <sect2 id="rts-optinos-environment">
-    <title>Setting global RTS options</title>
-
-    <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm>
-    <indexterm><primary>environment variable</primary><secondary>for
-    setting RTS options</secondary></indexterm>
-
-    <para>When the <literal>-rtsopts</literal> flag is used when linking,
-    RTS options are also taken from the environment variable
-    <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary>
-      </indexterm>.  For example, to set the maximum heap size
-    to 128M for all GHC-compiled programs (using an
-    <literal>sh</literal>-like shell):</para>
+        <para>
+          If you absolutely positively want all the rest of the options
+          in a command line to go to the program (and not the RTS), use a
+          <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.
+        </para>
+
+        <para>
+          As always, for RTS options that take
+          <replaceable>size</replaceable>s: If the last character of
+          <replaceable>size</replaceable> is a K or k, multiply by 1000; if an
+          M or m, by 1,000,000; if a G or G, by 1,000,000,000.  (And any
+          wraparound in the counters is <emphasis>your</emphasis>
+          fault!)
+        </para>
+
+        <para>
+          Giving a <literal>+RTS -?</literal>
+          <indexterm><primary><option>-?</option></primary><secondary>RTS option</secondary></indexterm> option
+          will print out the RTS options actually available in your program
+          (which vary, depending on how you compiled).</para>
+
+        <para>
+          NOTE: since GHC is itself compiled by GHC, you can change RTS
+          options in the compiler using the normal
+          <literal>+RTS ... -RTS</literal>
+          combination.  eg. to set the maximum heap
+          size for a compilation to 128M, you would add
+          <literal>+RTS -M128m -RTS</literal>
+          to the command line.
+        </para>
+      </sect3>
+
+      <sect3 id="rts-opts-compile-time">
+        <title>Setting RTS options at compile time</title>
+
+        <para>
+          GHC lets you change the default RTS options for a program at
+          compile time, using the <literal>-with-rtsopts</literal>
+          flag (<xref linkend="options-linker" />).  A common use for this is
+          to give your program a default heap and/or stack size that is
+          greater than the default.  For example, to set <literal>-H128m
+            -K64m</literal>, link
+          with <literal>-with-rtsopts="-H128m -K64m"</literal>.
+        </para>
+      </sect3>
+
+      <sect3 id="rts-options-environment">
+        <title>Setting RTS options with the <envar>GHCRTS</envar>
+          environment variable</title>
+
+        <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm>
+        <indexterm><primary>environment variable</primary><secondary>for
+            setting RTS options</secondary></indexterm>
+
+        <para>
+          If the <literal>-rtsopts</literal> flag is set to
+          something other than <literal>none</literal> when linking,
+          RTS options are also taken from the environment variable
+          <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary>
+          </indexterm>.  For example, to set the maximum heap size
+          to 2G for all GHC-compiled programs (using an
+          <literal>sh</literal>-like shell):
+        </para>
 
 <screen>
-   GHCRTS='-M128m'
+   GHCRTS='-M2G'
    export GHCRTS
 </screen>
 
-    <para>RTS options taken from the <envar>GHCRTS</envar> environment
-    variable can be overridden by options given on the command
-    line.</para>
+        <para>
+          RTS options taken from the <envar>GHCRTS</envar> environment
+          variable can be overridden by options given on the command
+          line.
+        </para>
 
-  </sect2>
+        <para>
+          Tip: setting something like <literal>GHCRTS=-M2G</literal>
+          in your environment is a handy way to avoid Haskell programs
+          growing beyond the real memory in your machine, which is
+          easy to do by accident and can cause the machine to slow to
+          a crawl until the OS decides to kill the process (and you
+          hope it kills the right one).
+        </para>
+      </sect3>
+
+  <sect3 id="rts-hooks">
+    <title>&ldquo;Hooks&rdquo; to change RTS behaviour</title>
+
+    <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
+    <indexterm><primary>RTS hooks</primary></indexterm>
+    <indexterm><primary>RTS behaviour, changing</primary></indexterm>
+
+    <para>GHC lets you exercise rudimentary control over certain RTS
+    settings for any given program, by compiling in a
+    &ldquo;hook&rdquo; that is called by the run-time system.  The RTS
+    contains stub definitions for these hooks, but by writing your
+    own version and linking it on the GHC command line, you can
+    override the defaults.</para>
+
+    <para>Owing to the vagaries of DLL linking, these hooks don't work
+    under Windows when the program is built dynamically.</para>
+
+    <para>You can change the messages printed when the runtime
+    system &ldquo;blows up,&rdquo; e.g., on stack overflow.  The hooks
+    for these are as follows:</para>
+
+    <variablelist>
+
+      <varlistentry>
+       <term>
+          <function>void OutOfHeapHook (unsigned long, unsigned long)</function>
+          <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
+        </term>
+       <listitem>
+         <para>The heap-overflow message.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <function>void StackOverflowHook (long int)</function>
+          <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
+        </term>
+       <listitem>
+         <para>The stack-overflow message.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <function>void MallocFailHook (long int)</function>
+          <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
+        </term>
+       <listitem>
+         <para>The message printed if <function>malloc</function>
+         fails.</para>
+       </listitem>
+      </varlistentry>
+    </variablelist>
+  </sect3>
+
+    </sect2>
 
   <sect2 id="rts-options-misc">
     <title>Miscellaneous RTS options</title>
            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
       </varlistentry>
 
       <varlistentry>
+        <term>
+          <option>-n</option><replaceable>size</replaceable>
+          <indexterm><primary><option>-n</option></primary><secondary>RTS option</secondary></indexterm>
+          <indexterm><primary>allocation area, chunk size</primary></indexterm>
+        </term>
+       <listitem>
+          <para>&lsqb;Default: 0, Example:
+          <literal>-n4m</literal>&rsqb; When set to a non-zero value,
+          this option divides the allocation area (<option>-A</option>
+          value) into chunks of the specified size.  During execution,
+          when a processor exhausts its current chunk, it is given
+          another chunk from the pool until the pool is exhausted, at
+          which point a collection is triggered.</para>
+
+          <para>This option is only useful when running in parallel
+          (<option>-N2</option> or greater).  It allows the processor
+          cores to make better use of the available allocation area,
+          even when cores are allocating at different rates.  Without
+          <option>-n</option>, each core gets a fixed-size allocation
+          area specified by the <option>-A</option>, and the first
+          core to exhaust its allocation area triggers a GC across all
+          the cores.  This can result in a collection happening when
+          the allocation areas of some cores are only partially full,
+          so the purpose of the <option>-n</option> is to allow cores
+          that are allocating faster to get more of the allocation
+          area.  This means less frequent GC, leading a lower GC
+          overhead for the same heap size.</para>
+
+          <para>This is particularly useful in conjunction with larger
+          <option>-A</option> values, for example <option>-A64m
+          -n4m</option> is a useful combination on larger core counts
+          (8+).</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term>
           <option>-c</option>
           <indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary></indexterm>
             generation <replaceable>gen</replaceable> and higher.
             Omitting <replaceable>gen</replaceable> turns off the
             parallel GC completely, reverting to sequential GC.</para>
-          
+
           <para>The default parallel GC settings are usually suitable
             for parallel programs (i.e. those
             using <literal>par</literal>, Strategies, or with multiple
             restrict parallel GC to the old generation
             with <literal>-qg1</literal>.</para>
         </listitem>
-      </varlistentry>        
+      </varlistentry>
 
       <varlistentry>
         <term>
             generation <replaceable>gen</replaceable> and higher.
             Omitting <replaceable>gen</replaceable> disables
             load-balancing entirely.</para>
-          
+
           <para>
             Load-balancing shares out the work of GC between the
             available cores.  This is a good idea when the heap is
 
       <varlistentry>
        <term>
-          <option>-H</option><replaceable>size</replaceable>
+          <option>-H</option><optional><replaceable>size</replaceable></optional>
           <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
           <indexterm><primary>heap size, suggested</primary></indexterm>
         </term>
        <listitem>
          <para>&lsqb;Default: 0&rsqb; This option provides a
-          &ldquo;suggested heap size&rdquo; for the garbage collector.  The
-          garbage collector will use about this much memory until the
-          program residency grows and the heap size needs to be
-          expanded to retain reasonable performance.</para>
-
-         <para>By default, the heap will start small, and grow and
-          shrink as necessary.  This can be bad for performance, so if
-          you have plenty of memory it's worthwhile supplying a big
-          <option>-H</option><replaceable>size</replaceable>.  For
-          improving GC performance, using
-          <option>-H</option><replaceable>size</replaceable> is
-          usually a better bet than
-          <option>-A</option><replaceable>size</replaceable>.</para>
-       </listitem>
+            &ldquo;suggested heap size&rdquo; for the garbage
+            collector.  Think
+            of <option>-H<replaceable>size</replaceable></option> as a
+            variable <option>-A</option> option.  It says: I want to
+            use at least <replaceable>size</replaceable> bytes, so use
+            whatever is left over to increase the <option>-A</option>
+            value.</para>
+
+          <para>This option does not put
+            a <emphasis>limit</emphasis> on the heap size: the heap
+            may grow beyond the given size as usual.</para>
+
+          <para>If <replaceable>size</replaceable> is omitted, then
+            the garbage collector will take the size of the heap at
+            the previous GC as the <replaceable>size</replaceable>.
+            This has the effect of allowing for a
+            larger <option>-A</option> value but without increasing
+            the overall memory requirements of the program.  It can be
+            useful when the default small <option>-A</option> value is
+            suboptimal, as it can be in programs that create large
+            amounts of long-lived data.</para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>
 
       <varlistentry>
        <term>
-         <option>-k</option><replaceable>size</replaceable>
+         <option>-ki</option><replaceable>size</replaceable>
          <indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm>
-         <indexterm><primary>stack, minimum size</primary></indexterm>
+         <indexterm><primary>stack, initial size</primary></indexterm>
         </term>
        <listitem>
-         <para>&lsqb;Default: 1k&rsqb; Set the initial stack size for
-          new threads.  Thread stacks (including the main thread's
-          stack) live on the heap, and grow as required.  The default
-          value is good for concurrent applications with lots of small
-          threads; if your program doesn't fit this model then
-          increasing this option may help performance.</para>
-
-         <para>The main thread is normally started with a slightly
-          larger heap to cut down on unnecessary stack growth while
-          the program is starting up.</para>
-       </listitem>
+          <para>
+            &lsqb;Default: 1k&rsqb; Set the initial stack size for new
+            threads.  (Note: this flag used to be
+            simply <option>-k</option>, but was renamed
+            to <option>-ki</option> in GHC 7.2.1.  The old name is
+            still accepted for backwards compatibility, but that may
+            be removed in a future version).
+          </para>
+
+          <para>
+            Thread stacks (including the main thread's stack) live on
+            the heap.  As the stack grows, new stack chunks are added
+            as required; if the stack shrinks again, these extra stack
+            chunks are reclaimed by the garbage collector.  The
+            default initial stack size is deliberately small, in order
+            to keep the time and space overhead for thread creation to
+            a minimum, and to make it practical to spawn threads for
+            even tiny pieces of work.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-kc</option><replaceable>size</replaceable>
+          <indexterm><primary><option>-kc</option></primary><secondary>RTS
+          option</secondary></indexterm>
+          <indexterm><primary>stack</primary><secondary>chunk size</secondary></indexterm>
+        </term>
+        <listitem>
+          <para>
+            &lsqb;Default: 32k&rsqb; Set the size of &ldquo;stack
+            chunks&rdquo;.  When a thread's current stack overflows, a
+            new stack chunk is created and added to the thread's
+            stack, until the limit set by <option>-K</option> is
+            reached.
+          </para>
+
+          <para>
+            The advantage of smaller stack chunks is that the garbage
+            collector can avoid traversing stack chunks if they are
+            known to be unmodified since the last collection, so
+            reducing the chunk size means that the garbage collector
+            can identify more stack as unmodified, and the GC overhead
+            might be reduced.  On the other hand, making stack chunks
+            too small adds some overhead as there will be more
+            overflow/underflow between chunks.  The default setting of
+            32k appears to be a reasonable compromise in most cases.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-kb</option><replaceable>size</replaceable>
+          <indexterm><primary><option>-kc</option></primary><secondary>RTS
+          option</secondary></indexterm>
+          <indexterm><primary>stack</primary><secondary>chunk buffer size</secondary></indexterm>
+        </term>
+        <listitem>
+          <para>
+            &lsqb;Default: 1k&rsqb; Sets the stack chunk buffer size.
+            When a stack chunk overflows and a new stack chunk is
+            created, some of the data from the previous stack chunk is
+            moved into the new chunk, to avoid an immediate underflow
+            and repeated overflow/underflow at the boundary.  The
+            amount of stack moved is set by the <option>-kb</option>
+            option.
+          </para>
+          <para>
+            Note that to avoid wasting space, this value should
+            typically be less than 10&percnt; of the size of a stack
+            chunk (<option>-kc</option>), because in a chain of stack
+            chunks, each chunk will have a gap of unused space of this
+            size.
+          </para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>
           <indexterm><primary>stack, maximum size</primary></indexterm>
         </term>
        <listitem>
-         <para>&lsqb;Default: 8M&rsqb; Set the maximum stack size for
-          an individual thread to <replaceable>size</replaceable>
-          bytes.  This option is there purely to stop the program
-          eating up all the available memory in the machine if it gets
-          into an infinite loop.</para>
+         <para>&lsqb;Default: 80% physical memory size&rsqb; Set the
+          maximum stack size for an individual thread to
+          <replaceable>size</replaceable> bytes. If the thread
+          attempts to exceed this limit, it will be sent the
+          <literal>StackOverflow</literal> exception. The
+          limit can be disabled entirely by specifying a size of zero.
+          </para>
+          <para>
+            This option is there mainly to stop the program eating up
+            all the available memory in the machine if it gets into an
+            infinite loop.
+          </para>
        </listitem>
       </varlistentry>
 
 
       <varlistentry>
         <term>
+          <option>-T</option>
+          <indexterm><primary><option>-T</option></primary><secondary>RTS option</secondary></indexterm>
+        </term>
+        <term>
           <option>-t</option><optional><replaceable>file</replaceable></optional>
           <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
          garbage collector, the amount of memory allocated, the
          maximum size of the heap, and so on.  The three
          variants give different levels of detail:
+          <option>-T</option> collects the data but produces no output
          <option>-t</option> produces a single line of output in the
          same format as GHC's <option>-Rghc-timing</option> option,
          <option>-s</option> produces a more detailed summary at the
           is sent to <constant>stderr</constant>.</para>
 
     <para>
+        If you use the <literal>-T</literal> flag then, you should
+        access the statistics using
+        <ulink url="&libraryBaseLocation;/GHC-Stats.html">GHC.Stats</ulink>.
+    </para>
+
+    <para>
         If you use the <literal>-t</literal> flag then, when your
         program finishes, you will see something like this:
     </para>
       </listitem>
       <listitem>
         <para>
-          The peak memory the RTS has allocated from the OS. 
+          The peak memory the RTS has allocated from the OS.
         </para>
       </listitem>
       <listitem>
       </listitem>
       <listitem>
         <para>
-          How many page faults occured this garbage collection.
+          How many page faults occurred this garbage collection.
         </para>
       </listitem>
       <listitem>
         <para>
-          How many page faults occured since the end of the last garbage
+          How many page faults occurred since the end of the last garbage
           collection.
         </para>
       </listitem>
               option</secondary></indexterm>
         </term>
         <listitem>
-          <para>Generates a basic heap profile, in the
+          <para>(can be shortened to <option>-h</option>.) Generates a basic heap profile, in the
             file <literal><replaceable>prog</replaceable>.hp</literal>.
             To produce the heap profile graph,
             use <command>hp2ps</command> (see <xref linkend="hp2ps"
         <para>
           In binary format to a file for later analysis by a
           variety of tools.  One such tool
-          is <ulink url="http://hackage.haskell.org/package/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>,
+          is <ulink url="http://www.haskell.org/haskellwiki/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>,
           which interprets the event log to produce a visual parallel
           execution profile of the program.
         </para>
         <listitem>
           <para>
             Log events in binary format to the
-            file <filename><replaceable>program</replaceable>.eventlog</filename>,
-            where <replaceable>flags</replaceable> is a sequence of
-            zero or more characters indicating which kinds of events
-            to log.  Currently there is only one type
-            supported: <literal>-ls</literal>, for scheduler events.
+            file <filename><replaceable>program</replaceable>.eventlog</filename>.
+            Without any <replaceable>flags</replaceable> specified, this logs a
+            default set of events, suitable for use with tools like ThreadScope.
+          </para>
+
+          <para>
+            For some special use cases you may want more control over which
+            events are included. The <replaceable>flags</replaceable> is a
+            sequence of zero or more characters indicating which classes of
+            events to log. Currently these the classes of events that can
+            be enabled/disabled:
+            <simplelist>
+              <member>
+                <option>s</option> &#8212; scheduler events, including Haskell
+                thread creation and start/stop events. Enabled by default.
+              </member>
+              <member>
+                <option>g</option> &#8212; GC events, including GC start/stop.
+                Enabled by default.
+              </member>
+              <member>
+                <option>p</option> &#8212; parallel sparks (sampled).
+                Enabled by default.
+              </member>
+              <member>
+                <option>f</option> &#8212; parallel sparks (fully accurate).
+                Disabled by default.
+              </member>
+              <member>
+                <option>u</option> &#8212; user events. These are events emitted
+                from Haskell code using functions such as 
+                <literal>Debug.Trace.traceEvent</literal>. Enabled by default.
+              </member>
+            </simplelist>
+          </para>
+
+          <para>            
+            You can disable specific classes, or enable/disable all classes at
+            once:
+            <simplelist>
+              <member>
+                <option>a</option> &#8212; enable all event classes listed above
+              </member>
+              <member>
+                <option>-<replaceable>x</replaceable></option> &#8212; disable the
+                given class of events, for any event class listed above or
+                <option>-a</option> for all classes
+              </member>
+            </simplelist>
+            For example, <option>-l-ag</option> would disable all event classes
+            (<option>-a</option>) except for GC events (<option>g</option>).
+          </para>
+
+          <para>            
+            For spark events there are two modes: sampled and fully accurate.
+            There are various events in the life cycle of each spark, usually
+            just creating and running, but there are some more exceptional
+            possibilities. In the sampled mode the number of occurrences of each
+            kind of spark event is sampled at frequent intervals. In the fully
+            accurate mode every spark event is logged individually. The latter
+            has a higher runtime overhead and is not enabled by default.
           </para>
 
           <para>
             the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
             library.  To dump the contents of
             a <literal>.eventlog</literal> file as text, use the
-            tool <literal>show-ghc-events</literal> that comes with
+            tool <literal>ghc-events show</literal> that comes with
             the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
             package.
           </para>
         </term>
        <listitem>
          <para>
-            An RTS debugging flag; only availble if the program was
+            An RTS debugging flag; only available if the program was
            linked with the <option>-debug</option> option.  Various
            values of <replaceable>x</replaceable> are provided to
            enable debug messages and additional runtime sanity checks
        <listitem>
          <para>(Only available when the program is compiled for
          profiling.)  When an exception is raised in the program,
-         this option causes the current cost-centre-stack to be
-         dumped to <literal>stderr</literal>.</para>
+          this option causes a stack trace to be
+          dumped to <literal>stderr</literal>.</para>
 
          <para>This can be particularly useful for debugging: if your
          program is complaining about a <literal>head []</literal>
          error and you haven't got a clue which bit of code is
          causing it, compiling with <literal>-prof
-         -auto-all</literal> and running with <literal>+RTS -xc
+          -fprof-auto</literal> and running with <literal>+RTS -xc
          -RTS</literal> will tell you exactly the call stack at the
          point the error was raised.</para>
 
-         <para>The output contains one line for each exception raised
-         in the program (the program might raise and catch several
-         exceptions during its execution), where each line is of the
-         form:</para>
+          <para>The output contains one report for each exception
+          raised in the program (the program might raise and catch
+          several exceptions during its execution), where each report
+          looks something like this:
+          </para>
 
 <screen>
-&lt; cc<subscript>1</subscript>, ..., cc<subscript>n</subscript> &gt;
+*** Exception raised (reporting due to +RTS -xc), stack trace:
+  GHC.List.CAF
+  --> evaluated by: Main.polynomial.table_search,
+  called from Main.polynomial.theta_index,
+  called from Main.polynomial,
+  called from Main.zonal_pressure,
+  called from Main.make_pressure.p,
+  called from Main.make_pressure,
+  called from Main.compute_initial_state.p,
+  called from Main.compute_initial_state,
+  called from Main.CAF
+  ...
 </screen>
-         <para>each <literal>cc</literal><subscript>i</subscript> is
-         a cost centre in the program (see <xref
-         linkend="cost-centres"/>), and the sequence represents the
-         &ldquo;call stack&rdquo; at the point the exception was
-         raised.  The leftmost item is the innermost function in the
-         call stack, and the rightmost item is the outermost
-         function.</para>
+          <para>The stack trace may often begin with something
+          uninformative like <literal>GHC.List.CAF</literal>; this is
+          an artifact of GHC's optimiser, which lifts out exceptions
+          to the top-level where the profiling system assigns them to
+          the cost centre "CAF".  However, <literal>+RTS -xc</literal>
+          doesn't just print the current stack, it looks deeper and
+          reports the stack at the time the CAF was evaluated, and it
+          may report further stacks until a non-CAF stack is found.  In
+          the example above, the next stack (after <literal>-->
+          evaluated by</literal>) contains plenty of information about
+          what the program was doing when it evaluated <literal>head
+          []</literal>.</para>
+
+          <para>Implementation details aside, the function names in
+          the stack should hopefully give you enough clues to track
+          down the bug.</para>
 
-       </listitem>
+          <para>
+            See also the function <literal>traceStack</literal> in the
+            module <literal>Debug.Trace</literal> for another way to
+            view call stacks.
+          </para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>
 
   </sect2>
 
-  <sect2>
-    <title>Linker flags to change RTS behaviour</title>
-
-    <indexterm><primary>RTS behaviour, changing</primary></indexterm>
-
-    <para>
-      GHC lets you exercise rudimentary control over the RTS settings
-      for any given program, by using the <literal>-with-rtsopts</literal>
-      linker flag. For example, to set <literal>-H128m -K1m</literal>,
-      link with <literal>-with-rtsopts="-H128m -K1m"</literal>.
-    </para>
-
-  </sect2>
-
-  <sect2 id="rts-hooks">
-    <title>&ldquo;Hooks&rdquo; to change RTS behaviour</title>
-
-    <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
-    <indexterm><primary>RTS hooks</primary></indexterm>
-    <indexterm><primary>RTS behaviour, changing</primary></indexterm>
-
-    <para>GHC lets you exercise rudimentary control over the RTS
-    settings for any given program, by compiling in a
-    &ldquo;hook&rdquo; that is called by the run-time system.  The RTS
-    contains stub definitions for all these hooks, but by writing your
-    own version and linking it on the GHC command line, you can
-    override the defaults.</para>
-
-    <para>Owing to the vagaries of DLL linking, these hooks don't work
-    under Windows when the program is built dynamically.</para>
-
-    <para>The hook <literal>ghc_rts_opts</literal><indexterm><primary><literal>ghc_rts_opts</literal></primary>
-      </indexterm>lets you set RTS
-    options permanently for a given program.  A common use for this is
-    to give your program a default heap and/or stack size that is
-    greater than the default.  For example, to set <literal>-H128m
-    -K1m</literal>, place the following definition in a C source
-    file:</para>
-
-<programlisting>
-char *ghc_rts_opts = "-H128m -K1m";
-</programlisting>
-
-    <para>Compile the C file, and include the object file on the
-    command line when you link your Haskell program.</para>
-
-    <para>These flags are interpreted first, before any RTS flags from
-    the <literal>GHCRTS</literal> environment variable and any flags
-    on the command line.</para>
-
-    <para>You can also change the messages printed when the runtime
-    system &ldquo;blows up,&rdquo; e.g., on stack overflow.  The hooks
-    for these are as follows:</para>
-
-    <variablelist>
-
-      <varlistentry>
-       <term>
-          <function>void OutOfHeapHook (unsigned long, unsigned long)</function>
-          <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
-        </term>
-       <listitem>
-         <para>The heap-overflow message.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <function>void StackOverflowHook (long int)</function>
-          <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
-        </term>
-       <listitem>
-         <para>The stack-overflow message.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <function>void MallocFailHook (long int)</function>
-          <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
-        </term>
-       <listitem>
-         <para>The message printed if <function>malloc</function>
-         fails.</para>
-       </listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>For examples of the use of these hooks, see GHC's own
-    versions in the file
-    <filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
-    source tree.</para>
-  </sect2>
-
-  <sect2>
+  <sect2 id="ghc-info">
     <title>Getting information about the RTS</title>
 
     <indexterm><primary>RTS</primary></indexterm>
@@ -1204,13 +1473,12 @@ $ ./a.out +RTS --info
         <term><literal>RTS way</literal></term>
         <listitem>
           <para>The variant (&ldquo;way&rdquo;) of the runtime. The
-          most common values are <literal>rts</literal> (vanilla),
+          most common values are <literal>rts_v</literal> (vanilla),
           <literal>rts_thr</literal> (threaded runtime, i.e. linked using the
           <literal>-threaded</literal> option) and <literal>rts_p</literal>
           (profiling runtime, i.e. linked using the <literal>-prof</literal>
           option). Other variants include <literal>debug</literal>
-          (linked using <literal>-debug</literal>),
-          <literal>t</literal> (ticky-ticky profiling) and
+          (linked using <literal>-debug</literal>), and
           <literal>dyn</literal> (the RTS is
           linked in dynamically, i.e. a shared library, rather than statically
           linked into the executable itself). These can be combined,
@@ -1270,7 +1538,8 @@ $ ./a.out +RTS --info
       <varlistentry>
         <term><literal>Compiler unregistered</literal></term>
         <listitem>
-          <para>Was this program compiled with an &ldquo;unregistered&rdquo;
+          <para>Was this program compiled with an
+          <link linkend="unreg">&ldquo;unregistered&rdquo;</link>
           version of GHC? (I.e., a version of GHC that has no platform-specific
           optimisations compiled in, usually because this is a currently
           unsupported platform.) This value will usually be no, unless you're