Add +RTS -n<size>: divide the nursery into chunks
[ghc.git] / docs / users_guide / runtime_control.xml
index aed507b..612a441 100644 (file)
@@ -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
@@ -1440,8 +1478,7 @@ $ ./a.out +RTS --info
           <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,