(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>
<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>-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
<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 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>
-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