<literal>+RTS -M128m -RTS</literal>
to the command line.</para>
+ <sect2 id="rts-optinos-environment">
+ <title>Setting global RTS options</title>
+
+ <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm>
+ <indexterm><primary>environment variable</primary><secondary>for
+ setting RTS options</secondary></indexterm>
+
+ <para>RTS options are also taken from the environment variable
+ <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary>
+ </indexterm>. For example, to set the maximum heap size
+ to 128M for all GHC-compiled programs (using an
+ <literal>sh</literal>-like shell):</para>
+
+<screen>
+ GHCRTS='-M128m'
+ export GHCRTS
+</screen>
+
+ <para>RTS options taken from the <envar>GHCRTS</envar> environment
+ variable can be overriden by options given on the command
+ line.</para>
+
+ </sect2>
+
<sect2 id="rts-options-gc">
- <title>RTS options to control the garbage-collector</title>
+ <title>RTS options to control the garbage collector</title>
- <indexterm><primary>RTS options, garbage-collection</primary></indexterm>
+ <indexterm><primary>garbage collector</primary><secondary>options</secondary></indexterm>
+ <indexterm><primary>RTS options</primary><secondary>garbage collection</secondary></indexterm>
<para>There are several options to give you precise control over
garbage collection. Hopefully, you won't need any of these in
</varlistentry>
<varlistentry>
+ <term><option>-c</option></term>
+ <indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary>
+ </indexterm>
+ <indexterm><primary>garbage collection</primary><secondary>compacting</secondary>
+ </indexterm>
+ <indexterm><primary>compacting garbage collection</primary></indexterm>
+
+ <listitem>
+ <para>Use a compacting algorithm for collecting the oldest
+ generation. By default, the oldest generation is collected
+ using a copying algorithm; this option causes it to be
+ compacted in-place instead. The compaction algorithm is
+ slower than the copying algorithm, but the savings in memory
+ use can be considerable.</para>
+
+ <para>For a given heap size (using the <option>-H</option>
+ option), compaction can in fact reduce the GC cost by
+ allowing fewer GCs to be performed. This is more likely
+ when the ratio of live data to heap size is high, say
+ >30%.</para>
+
+ <para>NOTE: compaction doesn't currently work when a single
+ generation is requested using the <option>-G1</option>
+ option.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-c</option><replaceable>n</replaceable></term>
+
+ <listitem>
+ <para>[Default: 30] Automatically enable
+ compacting collection when the live data exceeds
+ <replaceable>n</replaceable>% of the maximum heap size
+ (see the <option>-M</option> option). Note that the maximum
+ heap size is unlimited by default, so this option has no
+ effect unless the maximum heap size is set with
+ <option>-M</option><replaceable>size</replaceable>. </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-F</option><replaceable>factor</replaceable></Term>
<listitem>
<indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>heap size, maximum</primary></indexterm>
<listitem>
- <para>[Default: 64M] Set the maximum heap size to
+ <para>[Default: unlimited] Set the maximum heap size to
<replaceable>size</replaceable> bytes. The heap normally
grows and shrinks according to the memory requirements of
the program. The only reason for having this option is to
available swap space, which at the least will result in the
program being summarily killed by the operating
system.</para>
+
+ <para>The maximum heap size also affects other garbage
+ collection parameters: when the amount of live data in the
+ heap exceeds a certain fraction of the maximum heap size,
+ compacting collection will be automatically enabled for the
+ oldest generation, and the <option>-F</option> parameter
+ will be reduced in order to avoid exceeding the maximum heap
+ size.</para>
</listitem>
</varlistentry>
</sect2>
<!-- ---------------------------------------------------------------------- -->
- <sect2>
+ <sect2 id="rts-options-debugging">
<title>RTS options for hackers, debuggers, and over-interested
souls</title>
</varlistentry>
<varlistentry>
+ <term><option>-D</option><replaceable>num</replaceable></term>
+ <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm>
+ <listitem>
+ <para>An RTS debugging flag; varying quantities of output
+ depending on which bits are set in
+ <replaceable>num</replaceable>. Only works if the RTS was
+ compiled with the <option>DEBUG</option> option.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-r</option><replaceable>file</replaceable></term>
<indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>ticky ticky profiling</primary></indexterm>
</varlistentry>
<varlistentry>
- <term><option>-D</option><replaceable>num</replaceable></term>
- <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm>
+ <term><option>-xc</option></term>
+ <indexterm><primary><option>-xc</option></primary><secondary>RTS
+ option</secondary></indexterm>
<listitem>
- <para>An RTS debugging flag; varying quantities of output
- depending on which bits are set in
- <replaceable>num</replaceable>. Only works if the RTS was
- compiled with the <option>DEBUG</option> option.</para>
+ <para>(Only available when the program is compiled for
+ profiling.) When an exception is raised in the program,
+ this option causes the current cost-centre-stack to be
+ dumped to <literal>stderr</literal>.</para>
+
+ <para>This can be particularly useful for debugging: if your
+ program is complaining about a <literal>head []</literal>
+ error and you haven't got a clue which bit of code is
+ causing it, compiling with <literal>-prof
+ -auto-all</literal> and running with <literal>+RTS -xc
+ -RTS</literal> will tell you exactly the call stack at the
+ point the error was raised.</para>
</listitem>
</varlistentry>
projects / ghc-hetmet.git / blobdiff