increase the resolution of the time profiler.</para>
<para>Using a value of zero disables the RTS clock
- completetly, and has the effect of disabling timers that
+ completely, and has the effect of disabling timers that
depend on it: the context switch timer and the heap profiling
timer. Context switches will still happen, but
deterministically and at a rate much faster than normal.
</varlistentry>
<varlistentry>
+ <term>
+ <option>-g</option><replaceable>threads</replaceable>
+ <indexterm><primary><option>-g</option></primary><secondary>RTS option</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>[Default: 1] [new in GHC 6.10] Set the number
+ of threads to use for garbage collection. This option is
+ only accepted when the program was linked with the
+ <option>-threaded</option> option; see <xref
+ linkend="options-linker" />.</para>
+
+ <para>The garbage collector is able to work in parallel when
+ given more than one OS thread. Experiments have shown
+ that this usually results in a performance improvement
+ given 3 cores or more; with 2 cores it may or may not be
+ beneficial, depending on the workload. Bigger heaps work
+ better with parallel GC, so set your <option>-H</option>
+ value high (3 or more times the maximum residency). Look
+ at the timing stats with <option>+RTS -s</option> to
+ see whether you're getting any benefit from parallel GC or
+ not. If you find parallel GC is
+ significantly <emphasis>slower</emphasis> (in elapsed
+ time) than sequential GC, please report it as a
+ bug.</para>
+
+ <para>This value is set automatically when the
+ <option>-N</option> option is used, so the only reason to
+ use <option>-g</option> would be if you wanted to use a
+ different number of threads for GC than for execution.
+ For example, if your program is strictly single-threaded
+ but you still want to benefit from parallel GC, then it
+ might make sense to use <option>-g</option> rather than
+ <option>-N</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>
<option>-H</option><replaceable>size</replaceable>
<indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
</varlistentry>
<varlistentry>
+ <term>
+ <option>-t</option><optional><replaceable>file</replaceable></optional>
+ <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
+ </term>
<term>
- <option>-s</option><replaceable>file</replaceable>
+ <option>-s</option><optional><replaceable>file</replaceable></optional>
<indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
</term>
<term>
- <option>-S</option><replaceable>file</replaceable>
+ <option>-S</option><optional><replaceable>file</replaceable></optional>
<indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
</term>
<listitem>
- <para>Write modest (<option>-s</option>) or verbose
- (<option>-S</option>) garbage-collector statistics into file
- <replaceable>file</replaceable>. The default
- <replaceable>file</replaceable> is
- <filename><replaceable>program</replaceable>.stat</filename>. The
- <replaceable>file</replaceable> <constant>stderr</constant>
- is treated specially, with the output really being sent to
- <constant>stderr</constant>.</para>
-
- <para>This option is useful for watching how the storage
- manager adjusts the heap size based on the current amount of
- live data.</para>
- </listitem>
- </varlistentry>
+ <para>These options produce runtime-system statistics, such
+ as the amount of time spent executing the program and in the
+ 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> 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
+ end of the program, and <option>-S</option> additionally
+ produces information about each and every garbage
+ collection.</para>
- <varlistentry>
- <term>
- <option>-t<replaceable>file</replaceable></option>
- <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
- </term>
- <listitem>
- <para>Write a one-line GC stats summary after running the
- program. This output is in the same format as that produced
- by the <option>-Rghc-timing</option> option.</para>
-
- <para>As with <option>-s</option>, the default
- <replaceable>file</replaceable> is
- <filename><replaceable>program</replaceable>.stat</filename>. The
- <replaceable>file</replaceable> <constant>stderr</constant>
- is treated specially, with the output really being sent to
- <constant>stderr</constant>.</para>
+ <para>The output is placed in
+ <replaceable>file</replaceable>. If
+ <replaceable>file</replaceable> is omitted, then the output
+ is sent to <constant>stderr</constant>.</para>
</listitem>
</varlistentry>
</variablelist>