-<Sect1 id="runtime-control">
-<Title>Running a compiled program
-</Title>
-
-<Para>
-<IndexTerm><Primary>runtime control of Haskell programs</Primary></IndexTerm>
-<IndexTerm><Primary>running, compiled program</Primary></IndexTerm>
-<IndexTerm><Primary>RTS options</Primary></IndexTerm>
-</Para>
-
-<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>+RTS option</Primary></IndexTerm> and
-<Option>-RTS</Option><IndexTerm><Primary>-RTS option</Primary></IndexTerm> as its own. For example:
-</Para>
-
-<Para>
-
-<Screen>
-% ./a.out -f +RTS -p -S -RTS -h foo bar
-</Screen>
+<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>
+ <para>You have some control over the behaviour of the RTS, by giving
+ special command-line arguments to your program.</para>
-<Para>
-The RTS will snaffle <Option>-p -S</Option> for itself, and the remaining arguments
-<Option>-f -h foo bar</Option> will be handed to your program if/when it calls
-<Function>System.getArgs</Function>.
-</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>
-<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>
+% ./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>
+ <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>
+<screen>
% hls -ltr /usr/etc +RTS -A5m
-</Screen>
-
-</Para>
-
-<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>--RTS option</Primary></IndexTerm>.
-</Para>
-
-<Para>
-As always, for RTS options that take <Literal><size></Literal>s: If the last
-character of <Literal>size</Literal> 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 <Option>+RTS -f</Option><IndexTerm><Primary>-f RTS option</Primary></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-options-gc">
-<Title>RTS options to control the garbage-collector
-</Title>
-
-<Para>
-<IndexTerm><Primary>RTS options, garbage-collection</Primary></IndexTerm>
-</Para>
-
-<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>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-A<size></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-A<size> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>allocation area, size</Primary></IndexTerm>
-</Para>
-
-<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>-F<factor></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-F<factor> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>heap size, factor</Primary></IndexTerm>
-</Para>
-
-<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<size></Option> than to increase
-<Option>-F<factor></Option>.
-</Para>
-
-<Para>
-The <Option>-F</Option> setting will be automatically reduced by the garbage
-collector when the maximum heap size (the <Option>-M<size></Option> setting)
-is approaching.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-G<generations></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-G<generations> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>generations, number of</Primary></IndexTerm>
-</Para>
-
-<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 never 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<size></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-H<size> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>heap size, suggested</Primary></IndexTerm>
-</Para>
-
-<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<size></Option>. For
-improving GC performance, using <Option>-H<size></Option> is usually a better
-bet than <Option>-A<size></Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-k<size></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-k<size> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>stack, minimum size</Primary></IndexTerm>
-</Para>
-
-<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<size></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-K<size> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>stack, maximum size</Primary></IndexTerm>
-</Para>
-
-<Para>
-[Default: 1M] Set the maximum stack size for an individual thread to
-<Literal><size></Literal> 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<n></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-m<n> RTS option</Primary></IndexTerm>
-Minimum % <Literal><n></Literal> of heap which must be available for allocation.
-The default is 3%.
-<IndexTerm><Primary>heap, minimum free</Primary></IndexTerm>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-M<size></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-M<size> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>heap size, maximum</Primary></IndexTerm>
-</Para>
-
-<Para>
-[Default: 64M] Set the maximum heap size to <Literal><size></Literal> 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>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-s<file></Option> or <Option>-S<file></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-S<file> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>-s<file> RTS option</Primary></IndexTerm>
-Write modest (<Option>-s</Option>) or verbose (<Option>-S</Option>) garbage-collector
-statistics into file <Filename><file></Filename>. The default <Filename><file></Filename> is
-<Filename><program>@.stat</Filename>. The <Filename><file></Filename> <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>
-</VariableList>
-</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>
-
-</Sect2>
-
-<Sect2>
-<Title>RTS options for hackers, debuggers, and over-interested souls</Title>
-
-<Para>
-<IndexTerm><Primary>RTS options, hacking/debugging</Primary></IndexTerm>
-</Para>
-
-<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>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-B</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-B RTS option</Primary></IndexTerm>
-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>-r<file></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-r <file> RTS option</Primary></IndexTerm>
-<IndexTerm><Primary>ticky ticky profiling</Primary></IndexTerm>
-Produce “ticky-ticky” statistics at the end of the program run.
-The <Filename><file></Filename> 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>-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>-D<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-D RTS option</Primary></IndexTerm>
-An RTS debugging flag; varying quantities of output depending on which
-bits are set in <Literal><num></Literal>. Only works if the RTS was compiled with the
-<Option>DEBUG</Option> option.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-Z</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Z RTS option</Primary></IndexTerm>
-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>
-</Para>
-
-</Sect2>
-
-<Sect2 id="rts-hooks">
-<Title>“Hooks” to change RTS behaviour
-</Title>
-
-<Para>
-<IndexTerm><Primary>hooks, RTS</Primary></IndexTerm>
-<IndexTerm><Primary>RTS hooks</Primary></IndexTerm>
-<IndexTerm><Primary>RTS behaviour, changing</Primary></IndexTerm>
-</Para>
-
-<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 function <Function>defaultsHook</Function><IndexTerm><Primary>defaultHook</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 <Option>-H8m -K1m</Option>:
-</Para>
-
-<Para>
-
-<ProgramListing>
+</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-options-gc">
+ <title>RTS options to control the garbage-collector</title>
+
+ <indexterm><primary>RTS options, garbage-collection</primary></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>-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: 1M] 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: 64M] 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>
+ </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="prof-rts-options">; and those for concurrent/parallel
+ stuff, in <XRef LinkEnd="parallel-rts-opts">.</para>
+ </sect2>
+
+<!-- ---------------------------------------------------------------------- -->
+ <sect2>
+ <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>-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>-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>-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 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>
+
+<programlisting>
#include "Rts.h"
#include "RtsFlags.h"
void defaultsHook (void) {
- RTSflags.GcFlags.stksSize = 1000002 / sizeof(W_);
- RTSflags.GcFlags.heapSize = 8000002 / sizeof(W_);
-}
-</ProgramListing>
-
-</Para>
-
-<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>
-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>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Function>void ErrorHdrHook (FILE *)</Function>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>ErrorHdrHook</Primary></IndexTerm>
-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>
-<ListItem>
-<Para>
-<IndexTerm><Primary>OutOfHeapHook</Primary></IndexTerm>
-The heap-overflow message.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Function>void StackOverflowHook (long int)</Function>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>StackOverflowHook</Primary></IndexTerm>
-The stack-overflow message.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Function>void MallocFailHook (long int)</Function>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>MallocFailHook</Primary></IndexTerm>
-The message printed if <Function>malloc</Function> fails.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Function>void PatErrorHdrHook (FILE *)</Function>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>PatErrorHdrHook</Primary></IndexTerm>
-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>
-<ListItem>
-<Para>
-<IndexTerm><Primary>PreTraceHook</Primary></IndexTerm>
-What's printed out before a <Function>trace</Function> message.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Function>void PostTraceHook (FILE *)</Function>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>PostTraceHook</Primary></IndexTerm>
-What's printed out after a <Function>trace</Function> message.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-For example, here is the “hooks” code used by GHC itself:
-
-<ProgramListing>
-#include <stdio.h>
-#define W_ unsigned long int
-#define I_ long int
-
-void
-ErrorHdrHook (FILE *where)
-{
- fprintf(where, "\n"); /* no "Fail: " */
+ RtsFlags.GcFlags.maxStkSize = 1000002 / sizeof(W_);
+ RtsFlags.GcFlags.maxHeapSize = 128*1024*1024 / BLOCK_SIZE_W;
}
+</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>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 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>
+ <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>
+
+ <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
-OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
+defaultsHook (void)
{
- fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
- allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
- option to increase the total heap size.\n",
- request_size,
- heap_size);
+ 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
-StackOverflowHook (I_ stack_size) /* in bytes */
+ErrorHdrHook (long fd)
{
- fprintf(stderr, "GHC stack-space overflow: current size
- %ld bytes.\nUse the `-K<size>' option to increase it.\n",
- stack_size);
+ char msg[]="\n";
+ write(fd,msg,1);
}
void
-PatErrorHdrHook (FILE *where)
+PatErrorHdrHook (long fd)
{
- fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
- This is a compiler bug; please report it to
- glasgow-haskell-bugs@haskell.org.\n\nFail: ");
+ 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 (FILE *where)
+PreTraceHook (long fd)
{
- fprintf(where, "\n"); /* not "Trace On" */
+ const char msg[]="\n";
+ write(fd,msg,sizeof(msg)-1);
}
void
-PostTraceHook (FILE *where)
+PostTraceHook (long fd)
{
- fprintf(where, "\n"); /* not "Trace Off" */
+#if 0
+ const char msg[]="\n";
+ write(fd,msg,sizeof(msg)-1);
+#endif
}
-</ProgramListing>
-
-</Para>
-
-</Sect2>
+</programlisting>
-</Sect1>
+ </sect2>
+</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
projects / ghc-hetmet.git / commitdiff