<variablelist>
<varlistentry>
- <term><option>-V<replaceable>secs</replaceable></option></term>
+ <term><option>-V<replaceable>secs</replaceable></option>
<indexterm><primary><option>-V</option></primary><secondary>RTS
- option</secondary></indexterm>
+ option</secondary></indexterm></term>
<listitem>
<para>Sets the interval that the RTS clock ticks at. The
runtime uses a single timer signal to count ticks; this timer
signal is used to control the context switch timer (<xref
- linkend="sec-using-concurrent" />) and the heap profiling
+ linkend="using-concurrent" />) and the heap profiling
timer <xref linkend="rts-options-heap-prof" />. Also, the
time profiler uses the RTS timer signal directly to record
time profiling samples.</para>
the <option>-C</option> or <option>-i</option> options.
However, setting <option>-V</option> is required in order to
increase the resolution of the time profiler.</para>
+
+ <para>Using a value of zero disables the RTS clock
+ 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.
+ Disabling the interval timer is useful for debugging, because
+ it eliminates a source of non-determinism at runtime.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--install-signal-handlers=<replaceable>yes|no</replaceable></option>
+ <indexterm><primary><option>--install-signal-handlers</option></primary><secondary>RTS
+ option</secondary></indexterm></term>
+ <listitem>
+ <para>If yes (the default), the RTS installs signal handlers to catch
+ things like ctrl-C. This option is primarily useful for when
+ you are using the Haskell code as a DLL, and want to set your
+ own signal handlers.</para>
</listitem>
</varlistentry>
</variablelist>
</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>
<para>The RTS options related to profiling are described in <xref
linkend="rts-options-heap-prof"/>, those for concurrency in
- <xref linkend="sec-using-concurrent" />, and those for parallelism in
+ <xref linkend="using-concurrent" />, and those for parallelism in
<xref linkend="parallel-options"/>.</para>
</sect2>
<filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
source tree.</para>
</sect2>
+
+ <sect2>
+ <title>Getting information about the RTS</title>
+
+ <indexterm><primary>RTS</primary></indexterm>
+
+ <para>It is possible to ask the RTS to give some information about
+ itself. To do this, use the <option>--info</option> flag, e.g.</para>
+<screen>
+$ ./a.out +RTS --info
+ [("GHC RTS", "Yes")
+ ,("GHC version", "6.7")
+ ,("RTS way", "rts_p")
+ ,("Host platform", "x86_64-unknown-linux")
+ ,("Build platform", "x86_64-unknown-linux")
+ ,("Target platform", "x86_64-unknown-linux")
+ ,("Compiler unregisterised", "NO")
+ ,("Tables next to code", "YES")
+ ]
+</screen>
+ <para>The information is formatted such that it can be read as a
+ of type <literal>[(String, String)]</literal>.</para>
+ </sect2>
</sect1>
<!-- Emacs stuff: