Add +RTS -n<size>: divide the nursery into chunks
[ghc.git] / docs / users_guide / runtime_control.xml
index 793ceec..612a441 100644 (file)
@@ -100,7 +100,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
         <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>.
+          <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.
         </para>
 
         <para>
@@ -365,6 +365,42 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
       </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>
@@ -676,10 +712,12 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
           <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.  If the thread attempts to exceed this limit, it will
-            be send the <literal>StackOverflow</literal> exception.
+         <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
@@ -730,6 +768,10 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
 
       <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>
@@ -751,6 +793,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
          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
@@ -764,6 +807,12 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
           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>
@@ -1108,38 +1157,35 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
             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 there are four classes of events that can
+            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
+                thread creation and start/stop events. Enabled by default.
               </member>
               <member>
-                <option>g</option> &#8212; GC events, including GC start/stop
+                <option>g</option> &#8212; GC events, including GC start/stop.
+                Enabled by default.
               </member>
               <member>
-                <option>p</option> &#8212; parallel sparks (sampled)
+                <option>p</option> &#8212; parallel sparks (sampled).
+                Enabled by default.
               </member>
               <member>
-                <option>f</option> &#8212; parallel sparks (fully accurate)
+                <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>            
-            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 initial enabled event classes are 's', 'g' and 'p'. In addition
-            you can disable specific classes, or enable/disable all classes at
+            You can disable specific classes, or enable/disable all classes at
             once:
             <simplelist>
               <member>
@@ -1155,6 +1201,16 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
             (<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 format of the log file is described by the header
             <filename>EventLogFormat.h</filename> that comes with
@@ -1162,7 +1218,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
             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>ghc-events-show</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>
@@ -1290,7 +1346,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
        <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
+          this option causes a stack trace to be
           dumped to <literal>stderr</literal>.</para>
 
          <para>This can be particularly useful for debugging: if your
@@ -1337,6 +1393,12 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
           <para>Implementation details aside, the function names in
           the stack should hopefully give you enough clues to track
           down the bug.</para>
+
+          <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>
 
@@ -1411,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,