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.