--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<sect1 id="runtime-control">
+ <title>Running a compiled program</title>
+
+ <indexterm><primary>runtime control of Haskell programs</primary></indexterm>
+ <indexterm><primary>running, compiled program</primary></indexterm>
+ <indexterm><primary>RTS options</primary></indexterm>
+
+ <para>To make an executable program, the GHC system compiles your
+ code and then links it with a non-trivial runtime system (RTS),
+ which handles storage management, profiling, etc.</para>
+
+ <para>You have some control over the behaviour of the RTS, by giving
+ special command-line arguments to your program.</para>
+
+ <para>When your Haskell program starts up, its RTS extracts
+ command-line arguments bracketed between
+ <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm>
+ and
+ <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm>
+ as its own. For example:</para>
+
+<screen>
+% ./a.out -f +RTS -p -S -RTS -h foo bar
+</screen>
+
+ <para>The RTS will snaffle <option>-p</option> <option>-S</option>
+ for itself, and the remaining arguments <literal>-f -h foo bar</literal>
+ will be handed to your program if/when it calls
+ <function>System.getArgs</function>.</para>
+
+ <para>No <option>-RTS</option> option is required if the
+ runtime-system options extend to the end of the command line, as in
+ this example:</para>
+
+<screen>
+% hls -ltr /usr/etc +RTS -A5m
+</screen>
+
+ <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>
+
+ <para>As always, for RTS options that take
+ <replaceable>size</replaceable>s: If the last character of
+ <replaceable>size</replaceable> is a K or k, multiply by 1000; if an
+ M or m, by 1,000,000; if a G or G, by 1,000,000,000. (And any
+ wraparound in the counters is <emphasis>your</emphasis>
+ fault!)</para>
+
+ <para>Giving a <literal>+RTS -f</literal>
+ <indexterm><primary><option>-f</option></primary><secondary>RTS option</secondary></indexterm> option
+ will print out the RTS options actually available in your program
+ (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>
+ combination. eg. to increase the maximum heap
+ 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>
+
+ <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
+ normal operation, but there are several things that can be tweaked
+ for maximum performance.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <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>
+ <para>[Default: 256k] Set the allocation area size
+ 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
+ promotion).</para>
+
+ <para>With only 1 generation (<option>-G1</option>) the
+ <option>-A</option> option specifies the minimum allocation
+ area, since the actual size of the allocation area will be
+ resized according to the amount of data in the heap (see
+ <option>-F</option>, below).</para>
+ </listitem>
+ </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>heap size, factor</primary></indexterm>
+
+ <para>[Default: 2] This option controls the amount
+ of memory reserved for the older generations (and in the
+ case of a two space collector the size of the allocation
+ area) as a factor of the amount of live data. For example,
+ if there was 2M of live data in the oldest generation when
+ we last collected it, then by default we'll wait until it
+ grows to 4M before collecting it again.</para>
+
+ <para>The default seems to work well here. If you have
+ plenty of memory, it is usually better to use
+ <option>-H</option><replaceable>size</replaceable> than to
+ increase
+ <option>-F</option><replaceable>factor</replaceable>.</para>
+
+ <para>The <option>-F</option> setting will be automatically
+ reduced by the garbage collector when the maximum heap size
+ (the <option>-M</option><replaceable>size</replaceable>
+ setting) is approaching.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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>
+ <listitem>
+ <para>[Default: 2] Set the number of generations
+ used by the garbage collector. The default of 2 seems to be
+ good, but the garbage collector can support any number of
+ generations. Anything larger than about 4 is probably not a
+ good idea unless your program runs for a
+ <emphasis>long</emphasis> time, because the oldest
+ generation will hardly ever get collected.</para>
+
+ <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
+ 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>
+ <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>
+ <listitem>
+ <para>[Default: 0] This option provides a
+ “suggested heap size” for the garbage collector. The
+ garbage collector will use about this much memory until the
+ program residency grows and the heap size needs to be
+ expanded to retain reasonable performance.</para>
+
+ <para>By default, the heap will start small, and grow and
+ shrink as necessary. This can be bad for performance, so if
+ you have plenty of memory it's worthwhile supplying a big
+ <option>-H</option><replaceable>size</replaceable>. For
+ improving GC performance, using
+ <option>-H</option><replaceable>size</replaceable> is
+ usually a better bet than
+ <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>stack, minimum size</primary></indexterm>
+ <listitem>
+ <para>[Default: 1k] Set the initial stack size for
+ new threads. Thread stacks (including the main thread's
+ stack) live on the heap, and grow as required. The default
+ value is good for concurrent applications with lots of small
+ threads; if your program doesn't fit this model then
+ increasing this option may help performance.</para>
+
+ <para>The main thread is normally started with a slightly
+ larger heap to cut down on unnecessary stack growth while
+ the program is starting up.</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>stack, maximum size</primary></indexterm>
+ <listitem>
+ <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
+ into an infinite loop.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-m</option><replaceable>n</replaceable></term>
+ <indexterm><primary><option>-m</option></primary><secondary>RTS option</secondary></indexterm>
+ <indexterm><primary>heap, minimum free</primary></indexterm>
+ <listitem>
+ <para>Minimum % <replaceable>n</replaceable> of heap
+ which must be available for allocation. The default is
+ 3%.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-M</option><replaceable>size</replaceable></term>
+ <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm>
+ <indexterm><primary>heap size, maximum</primary></indexterm>
+ <listitem>
+ <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
+ stop the heap growing without bound and filling up all the
+ 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>
+ <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
+ <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
+ <listitem>
+ <para>Write modest (<option>-s</option>) or verbose
+ (<option>-S</option>) garbage-collector statistics into file
+ <replaceable>file</replaceable>. The default
+ <replaceable>file</replaceable> is
+ <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>
+
+ <para>This option is useful for watching how the storage
+ manager adjusts the heap size based on the current amount of
+ live data.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-t</option></term>
+ <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
+ <listitem>
+ <para>Write a one-line GC stats summary after running the
+ program. This output is in the same format as that produced
+ by the <option>-Rghc-timing</option> option.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>RTS options for profiling and Concurrent/Parallel Haskell</title>
+
+ <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>
+
+ <indexterm><primary>RTS options, hacking/debugging</primary></indexterm>
+
+ <para>These RTS options might be used (a) to avoid a GHC bug,
+ (b) to see “what's really happening”, or
+ (c) because you feel like it. Not recommended for everyday
+ use!</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-B</option></term>
+ <indexterm><primary><option>-B</option></primary><secondary>RTS option</secondary></indexterm>
+ <listitem>
+ <para>Sound the bell at the start of each (major) garbage
+ collection.</para>
+
+ <para>Oddly enough, people really do use this option! Our
+ pal in Durham (England), Paul Callaghan, writes: “Some
+ people here use it for a variety of
+ purposes—honestly!—e.g., confirmation that the
+ code/machine is doing something, infinite loop detection,
+ gauging cost of recently added code. Certain people can even
+ tell what stage [the program] is in by the beep
+ pattern. But the major use is for annoying others in the
+ same office…”</para>
+ </listitem>
+ </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>
+ <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm>
+ <listitem>
+ <para>Produce “ticky-ticky” statistics at the
+ end of the program run. The <replaceable>file</replaceable>
+ business works just like on the <option>-S</option> RTS
+ option (above).</para>
+
+ <para>“Ticky-ticky” statistics are counts of
+ various program actions (updates, enters, etc.) The program
+ must have been compiled using
+ <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
+ (a.k.a. “ticky-ticky profiling”), and, for it to
+ 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-xc</option></term>
+ <indexterm><primary><option>-xc</option></primary><secondary>RTS
+ option</secondary></indexterm>
+ <listitem>
+ <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>
+
+ <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>
+
+ <varlistentry>
+ <term><option>-Z</option></term>
+ <indexterm><primary><option>-Z</option></primary><secondary>RTS
+ option</secondary></indexterm>
+ <listitem>
+ <para>Turn <emphasis>off</emphasis> “update-frame
+ squeezing” at garbage-collection time. (There's no
+ particularly good reason to turn it off, except to ensure
+ the accuracy of certain data collected regarding thunk entry
+ counts.)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="rts-hooks">
+ <title>“Hooks” to change RTS behaviour</title>
+
+ <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
+ <indexterm><primary>RTS hooks</primary></indexterm>
+ <indexterm><primary>RTS behaviour, changing</primary></indexterm>
+
+ <para>GHC lets you exercise rudimentary control over the RTS
+ settings for any given program, by compiling in a
+ “hook” that is called by the run-time system. The RTS
+ contains stub definitions for all these hooks, but by writing your
+ own version and linking it on the GHC command line, you can
+ override the defaults.</para>
+
+ <para>Owing to the vagaries of DLL linking, these hooks don't work
+ under Windows when the program is built dynamically.</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>
+char *ghc_rts_opts = "-H128m -K1m";
+</programlisting>
+
+ <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
+ for these are as follows:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term>
+ <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
+ <listitem>
+ <para>The heap-overflow message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>void StackOverflowHook (long int)</function></term>
+ <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
+ <listitem>
+ <para>The stack-overflow message.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+ fails.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <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>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: xml ***
+ ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff