<para>If you absolutely positively want all the rest of the options
in a command line to go to the program (and not the RTS), use a
- <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.</para>
+ <option>––RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.</para>
<para>As always, for RTS options that take
<replaceable>size</replaceable>s: If the last character of
(which vary, depending on how you compiled).</para>
<para>NOTE: since GHC is itself compiled by GHC, you can change RTS
- options in the compiler using the normal
- <literal>+RTS ... -RTS</literal>
+ options in the compiler using the normal
+ <literal>+RTS ... -RTS</literal>
combination. eg. to increase the maximum heap
- size for a compilation to 128M, you would add
+ size for a compilation to 128M, you would add
<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
<variablelist>
<varlistentry>
- <term><option>-A</option><replaceable>size</replaceable></Term>
+ <term><option>-A</option><replaceable>size</replaceable></term>
<indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>allocation area, size</primary></indexterm>
<listitem>
used by the garbage collector. The allocation area
(actually generation 0 step 0) is fixed and is never resized
(unless you use <option>-H</option>, below).</para>
-
+
<para>Increasing the allocation area size may or may not
give better performance (a bigger allocation area means
worse cache behaviour but fewer garbage collections and less
</varlistentry>
<varlistentry>
- <term><option>-F</option><replaceable>factor</replaceable></Term>
+ <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>heap size, factor</primary></indexterm>
</varlistentry>
<varlistentry>
- <term><option>-G</option><replaceable>generations</replaceable></Term>
+ <term><option>-G</option><replaceable>generations</replaceable></term>
<indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>generations, number
of</primary></indexterm>
<para>Specifying 1 generation with <option>+RTS -G1</option>
gives you a simple 2-space collector, as you would expect.
In a 2-space collector, the <option>-A</option> option (see
- above) specifies the <Emphasis>minimum</Emphasis> allocation
+ above) specifies the <emphasis>minimum</emphasis> allocation
area size, since the allocation area will grow with the
amount of live data in the heap. In a multi-generational
collector the allocation area is a fixed size (unless you
use the <option>-H</option> option, see below).</para>
</listitem>
</varlistentry>
-
- <VarListEntry>
+
+ <varlistentry>
<term><option>-H</option><replaceable>size</replaceable></term>
<indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>heap size, suggested</primary></indexterm>
<option>-A</option><replaceable>size</replaceable>.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><option>-k</option><replaceable>size</replaceable></term>
<indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary><option>-K</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>stack, maximum size</primary></indexterm>
<listitem>
- <para>[Default: 1M] Set the maximum stack size for
+ <para>[Default: 8M] Set the maximum stack size for
an individual thread to <replaceable>size</replaceable>
bytes. This option is there purely to stop the program
eating up all the available memory in the machine if it gets
<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>
<varlistentry>
<term><option>-s</option><replaceable>file</replaceable></term>
- <term><option>-S</option><replaceable>file</replaceable></Term>
+ <term><option>-S</option><replaceable>file</replaceable></term>
<indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
<listitem>
(<option>-S</option>) garbage-collector statistics into file
<replaceable>file</replaceable>. The default
<replaceable>file</replaceable> is
- <Filename><replaceable>program</replaceable>.stat</Filename>. The
+ <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>
</sect2>
-<!-- ---------------------------------------------------------------------- -->
<sect2>
<title>RTS options for profiling and Concurrent/Parallel Haskell</title>
- <para>The RTS options related to profiling are described in <XRef
- LinkEnd="prof-rts-options">; and those for concurrent/parallel
- stuff, in <XRef LinkEnd="parallel-rts-opts">.</para>
+ <para>The RTS options related to profiling are described in <xref
+ linkend="rts-options-heap-prof"/>; and those for concurrent/parallel
+ stuff, in <xref linkend="parallel-rts-opts"/>.</para>
</sect2>
-<!-- ---------------------------------------------------------------------- -->
- <sect2>
+ <sect2 id="rts-options-debugging">
<title>RTS options for hackers, debuggers, and over-interested
souls</title>
be really useful, linked with suitable system libraries.
Not a trivial undertaking: consult the installation guide on
how to set things up for easy “ticky-ticky”
- profiling. For more information, see <XRef
- LinkEnd="ticky-ticky">.</para>
+ profiling. For more information, see <xref
+ linkend="ticky-ticky"/>.</para>
</listitem>
</varlistentry>
- <varlistentry id="stack-trace-option">
+ <varlistentry>
<term><option>-xc</option></term>
<indexterm><primary><option>-xc</option></primary><secondary>RTS
option</secondary></indexterm>
-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>
+
+ <para>The output contains one line for each exception raised
+ in the program (the program might raise and catch several
+ exceptions during its execution), where each line is of the
+ form:</para>
+
+<screen>
+< cc<subscript>1</subscript>, ..., cc<subscript>n</subscript> >
+</screen>
+ <para>each <literal>cc</literal><subscript>i</subscript> is
+ a cost centre in the program (see <xref
+ linkend="cost-centres"/>), and the sequence represents the
+ “call stack” at the point the exception was
+ raised. The leftmost item is the innermost function in the
+ call stack, and the rightmost item is the outermost
+ function.</para>
+
</listitem>
</varlistentry>
</listitem>
</varlistentry>
</variablelist>
-
+
</sect2>
-
+
<sect2 id="rts-hooks">
<title>“Hooks” to change RTS behaviour</title>
<para>Owing to the vagaries of DLL linking, these hooks don't work
under Windows when the program is built dynamically.</para>
- <para>The function
- <Function>defaultsHook</Function><indexterm><primary><function>defaultHook</function></primary></indexterm>
- lets you change various RTS options. The commonest use for this
- is to give your program a default heap and/or stack size that is
- greater than the default. For example, to set
- <literal>-M128m -K1m</literal>:</para>
+ <para>The hook <literal>ghc_rts_opts</literal><indexterm><primary><literal>ghc_rts_opts</literal></primary>
+ </indexterm>lets you set RTS
+ options permanently for a given program. A common use for this is
+ to give your program a default heap and/or stack size that is
+ greater than the default. For example, to set <literal>-H128m
+ -K1m</literal>, place the following definition in a C source
+ file:</para>
<programlisting>
-#include "Rts.h"
-#include "RtsFlags.h"
-void defaultsHook (void) {
- RtsFlags.GcFlags.maxStkSize = 1000002 / sizeof(W_);
- RtsFlags.GcFlags.maxHeapSize = 128*1024*1024 / BLOCK_SIZE_W;
-}
+char *ghc_rts_opts = "-H128m -K1m";
</programlisting>
- <para>Don't use powers of two for heap/stack sizes: these are more
- likely to interact badly with direct-mapped caches. The full set
- of flags is defined in <Filename>ghc/rts/RtsFlags.h</Filename> the
- the GHC source tree.</para>
+ <para>Compile the C file, and include the object file on the
+ command line when you link your Haskell program.</para>
+
+ <para>These flags are interpreted first, before any RTS flags from
+ the <literal>GHCRTS</literal> environment variable and any flags
+ on the command line.</para>
<para>You can also change the messages printed when the runtime
system “blows up,” e.g., on stack overflow. The hooks
<variablelist>
<varlistentry>
- <term><Function>void ErrorHdrHook (FILE *)</function></term>
- <indexterm><primary><function>ErrorHdrHook</function></primary></indexterm>
- <listitem>
- <para>What's printed out before the message from
- <function>error</function>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term>
<indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
- <ListItem>
+ <listitem>
<para>The heap-overflow message.</para>
</listitem>
</varlistentry>
<term><function>void MallocFailHook (long int)</function></term>
<indexterm><primary><function>MallocFailHook</function></primary></indexterm>
<listitem>
- <para>The message printed if <Function>malloc</Function>
+ <para>The message printed if <function>malloc</function>
fails.</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><function>void PatErrorHdrHook (FILE *)</function></term>
- <indexterm><primary><function>PatErrorHdrHook</function></primary></indexterm>
- <listitem>
- <para>The message printed if a pattern-match fails (the
- failures that were not handled by the Haskell
- programmer).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>void PreTraceHook (FILE *)</function></term>
- <indexterm><primary><function>PreTraceHook</function></primary></indexterm>
- <listitem>
- <para>What's printed out before a <Function>trace</Function>
- message.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>void PostTraceHook (FILE *)</function></term>
- <indexterm><primary><function>PostTraceHook</function></primary></indexterm>
- <listitem>
- <para>What's printed out after a <Function>trace</Function>
- message.</para>
- </listitem>
- </varlistentry>
</variablelist>
- <para>For example, here is the “hooks” code used by
- GHC itself:</para>
-
-<programlisting>
-#include "Rts.h"
-#include "../rts/RtsFlags.h"
-#include "HsFFI.h"
-
-void
-defaultsHook (void)
-{
- RtsFlags.GcFlags.heapSizeSuggestion = 6*1024*1024 / BLOCK_SIZE;
- RtsFlags.GcFlags.maxStkSize = 8*1024*1024 / sizeof(W_);
- RtsFlags.GcFlags.giveStats = COLLECT_GC_STATS;
- RtsFlags.GcFlags.statsFile = stderr;
-}
-
-void
-ErrorHdrHook (long fd)
-{
- char msg[]="\n";
- write(fd,msg,1);
-}
-
-void
-PatErrorHdrHook (long fd)
-{
- const char msg[]="\n*** Pattern-matching error within GHC!\n\nThis is a compiler bug; please report it to glasgow-haskell-bugs@haskell.org.\n\nFail:";
- write(fd,msg,sizeof(msg)-1);
-}
-
-void
-PreTraceHook (long fd)
-{
- const char msg[]="\n";
- write(fd,msg,sizeof(msg)-1);
-}
-
-void
-PostTraceHook (long fd)
-{
-#if 0
- const char msg[]="\n";
- write(fd,msg,sizeof(msg)-1);
-#endif
-}
-</programlisting>
-
+ <para>For examples of the use of these hooks, see GHC's own
+ versions in the file
+ <filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
+ source tree.</para>
</sect2>
</sect1>
projects / ghc-hetmet.git / blobdiff