own signal handlers.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>-xm<replaceable>address</replaceable></option>
+ <indexterm><primary><option>-xm</option></primary><secondary>RTS
+ option</secondary></indexterm></term>
+ <listitem>
+ <para>
+ WARNING: this option is for working around memory
+ allocation problems only. Do not use unless GHCi fails
+ with a message like “<literal>failed to mmap() memory below 2Gb</literal>”. 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
+ different operating systems is patchy, and sometimes fails.
+ This option is there to give the RTS a hint about where it
+ should be able to allocate memory in the low 2Gb of the
+ address space. For example, <literal>+RTS -xm20000000
+ -RTS</literal> would hint that the RTS should allocate
+ starting at the 0.5Gb mark. The default is to use the OS's
+ built-in support for allocating memory in the low 2Gb if
+ available (e.g. <literal>mmap</literal>
+ with <literal>MAP_32BIT</literal> on Linux), or
+ otherwise <literal>-xm40000000</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect2>
<option>-S</option><optional><replaceable>file</replaceable></optional>
<indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
</term>
+ <term>
+ <option>--machine-readable</option>
+ <indexterm><primary><option>--machine-readable</option></primary><secondary>RTS option</secondary></indexterm>
+ </term>
<listitem>
<para>These options produce runtime-system statistics, such
as the amount of time spent executing the program and in the
</itemizedlist>
<para>
+ You can also get this in a more future-proof, machine readable
+ format, with <literal>-t --machine-readable</literal>:
+ </para>
+
+<programlisting>
+ [("bytes allocated", "36169392")
+ ,("num_GCs", "69")
+ ,("average_bytes_used", "603392")
+ ,("max_bytes_used", "1065272")
+ ,("num_byte_usage_samples", "2")
+ ,("peak_megabytes_allocated", "3")
+ ,("init_cpu_seconds", "0.00")
+ ,("init_wall_seconds", "0.00")
+ ,("mutator_cpu_seconds", "0.02")
+ ,("mutator_wall_seconds", "0.02")
+ ,("GC_cpu_seconds", "0.07")
+ ,("GC_wall_seconds", "0.07")
+ ]
+</programlisting>
+
+ <para>
If you use the <literal>-s</literal> flag then, when your
program finishes, you will see something like this (the exact
details will vary depending on what sort of RTS you have, e.g.
Generation 0: 67 collections, 0 parallel, 0.04s, 0.03s elapsed
Generation 1: 2 collections, 0 parallel, 0.03s, 0.04s elapsed
+ SPARKS: 359207 (557 converted, 149591 pruned)
+
INIT time 0.00s ( 0.00s elapsed)
MUT time 0.01s ( 0.02s elapsed)
GC time 0.07s ( 0.07s elapsed)
</para>
</listitem>
<listitem>
+ <para>The <literal>SPARKS</literal> statistic refers to the
+ use of <literal>Control.Parallel.par</literal> and related
+ functionality in the program. Each spark represents a call
+ to <literal>par</literal>; a spark is "converted" when it is
+ executed in parallel; and a spark is "pruned" when it is
+ found to be already evaluated and is discarded from the pool
+ by the garbage collector. Any remaining sparks are
+ discarded at the end of execution, so "converted" plus
+ "pruned" does not necessarily add up to the total.</para>
+ </listitem>
+ <listitem>
<para>
Next there is the CPU time and wall clock time elapsedm broken
down by what the runtiem system was doing at the time.
</sect2>
<sect2>
- <title>RTS options for profiling and parallelism</title>
+ <title>RTS options for concurrency and parallelism</title>
- <para>The RTS options related to profiling are described in <xref
- linkend="rts-options-heap-prof"/>, those for concurrency in
+ <para>The RTS options related to concurrency are described in
<xref linkend="using-concurrent" />, and those for parallelism in
<xref linkend="parallel-options"/>.</para>
</sect2>
+ <sect2 id="rts-profiling">
+ <title>RTS options for profiling</title>
+
+ <para>Most profiling runtime options are only available when you
+ compile your program for profiling (see
+ <xref linkend="prof-compiler-options" />, and
+ <xref linkend="rts-options-heap-prof" /> for the runtime options).
+ However, there is one profiling option that is available
+ for ordinary non-profiled executables:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>-hT</option>
+ <indexterm><primary><option>-hT</option></primary><secondary>RTS
+ option</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>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"
+ />). The basic heap profile is broken down by data
+ constructor, with other types of closures (functions, thunks,
+ etc.) grouped into broad categories
+ (e.g. <literal>FUN</literal>, <literal>THUNK</literal>). To
+ get a more detailed profile, use the full profiling
+ support (<xref linkend="profiling" />).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
<sect2 id="rts-options-debugging">
<title>RTS options for hackers, debuggers, and over-interested
souls</title>