<Para>
When your Haskell program starts up, its RTS extracts command-line
-arguments bracketed between <Literal>+RTS</Literal><IndexTerm><Primary>+RTS option</Primary></IndexTerm> and
-<Literal>-RTS</Literal><IndexTerm><Primary>-RTS option</Primary></IndexTerm> as its own. For example:
+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>
</Para>
<Para>
-The RTS will snaffle <Literal>-p -S</Literal> for itself, and the remaining arguments
-<Literal>-f -h foo bar</Literal> will be handed to your program if/when it calls
-<Literal>System.getArgs</Literal>.
+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>
-No <Literal>-RTS</Literal> option is required if the runtime-system options extend to
+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>
<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
-<Literal>--RTS</Literal><IndexTerm><Primary>--RTS option</Primary></IndexTerm>.
+<Option>--RTS</Option><IndexTerm><Primary>--RTS option</Primary></IndexTerm>.
</Para>
<Para>
</Para>
<Para>
-Giving a <Literal>+RTS -f</Literal><IndexTerm><Primary>-f RTS option</Primary></IndexTerm> option will print out the
+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: to send RTS options to the compiler itself, you need to prefix
-the option with <Literal>-optCrts</Literal>, eg. to increase the maximum heap size for
-a compilation to 128M, you would add <Literal>-optCrts-M128m</Literal> to the command
+the option with <Option>-optCrts</Option>, eg. to increase the maximum heap size for
+a compilation to 128M, you would add <Option>-optCrts-M128m</Option> to the command
line. The compiler understands some options directly without needing
-<Literal>-optCrts</Literal>: these are <Literal>-H</Literal> and <Literal>-K</Literal>.
+<Option>-optCrts</Option>: these are <Option>-H</Option> and <Option>-K</Option>.
</Para>
<Sect2 id="rts-options-gc">
<VariableList>
<VarListEntry>
-<Term><Literal>-A<size></Literal>:</Term>
+<Term><Option>-A<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-A<size> RTS option</Primary></IndexTerm>
<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 <Literal>-H</Literal>, below).
+fixed and is never resized (unless you use <Option>-H</Option>, below).
</Para>
<Para>
</Para>
<Para>
-With only 1 generation (<Literal>-G1</Literal>) the <Literal>-A</Literal> option specifies the
+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
-<Literal>-F</Literal>, below).
+<Option>-F</Option>, below).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-F<factor></Literal>:</Term>
+<Term><Option>-F<factor></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-F<factor> RTS option</Primary></IndexTerm>
<Para>
The default seems to work well here. If you have plenty of memory, it
-is usually better to use <Literal>-H<size></Literal> than to increase
-<Literal>-F<factor></Literal>.
+is usually better to use <Option>-H<size></Option> than to increase
+<Option>-F<factor></Option>.
</Para>
<Para>
-The <Literal>-F</Literal> setting will be automatically reduced by the garbage
-collector when the maximum heap size (the <Literal>-M<size></Literal> setting)
+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><Literal>-G<generations></Literal>:</Term>
+<Term><Option>-G<generations></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-G<generations> RTS option</Primary></IndexTerm>
</Para>
<Para>
-Specifying 1 generation with <Literal>+RTS -G1</Literal> gives you a simple 2-space
-collector, as you would expect. In a 2-space collector, the <Literal>-A</Literal>
+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 <Literal>-H</Literal> option, see below).
+fixed size (unless you use the <Option>-H</Option> option, see below).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-H<size></Literal>:</Term>
+<Term><Option>-H<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-H<size> RTS option</Primary></IndexTerm>
<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 <Literal>-H<size></Literal>. For
-improving GC performance, using <Literal>-H<size></Literal> is usually a better
-bet than <Literal>-A<size></Literal>.
+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><Literal>-k<size></Literal>:</Term>
+<Term><Option>-k<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-k<size> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-K<size></Literal>:</Term>
+<Term><Option>-K<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-K<size> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-m<n></Literal>:</Term>
+<Term><Option>-m<n></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-m<n> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-M<size></Literal>:</Term>
+<Term><Option>-M<size></Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-M<size> RTS option</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-s<file></Literal> or <Literal>-S<file></Literal>:</Term>
+<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 (<Literal>-s</Literal>) or verbose (<Literal>-S</Literal>) garbage-collector
-statistics into file <Literal><file></Literal>. The default <Literal><file></Literal> is
-<Literal><program>@.stat</Literal>. The <Literal><file></Literal> <Literal>stderr</Literal> is treated
-specially, with the output really being sent to <Literal>stderr</Literal>.
+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>
<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
+“what's really happening”, or (c) because you feel like it. Not
recommended for everyday use!
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>-B</Literal>:</Term>
+<Term><Option>-B</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-B RTS option</Primary></IndexTerm>
<Para>
Oddly enough, people really do use this option! Our pal in Durham
-(England), Paul Callaghan, writes: ``Some people here use it for a
+(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…''
+others in the same office…”
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-r<file></Literal>:</Term>
+<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 <Literal><file></Literal> business works just like on the <Literal>-S</Literal> RTS option (above).
+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
+“Ticky-ticky” statistics are counts of various program actions
(updates, enters, etc.) The program must have been compiled using
-<Literal>-ticky</Literal><IndexTerm><Primary>-ticky option</Primary></IndexTerm> (a.k.a. ``ticky-ticky profiling''),
+<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
+on how to set things up for easy “ticky-ticky” profiling. For more
information, see <XRef LinkEnd="ticky-ticky">.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-D<num></Literal>:</Term>
+<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
-<Literal>DEBUG</Literal> option.
+<Option>DEBUG</Option> option.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>-Z</Literal>:</Term>
+<Term><Option>-Z</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-Z RTS option</Primary></IndexTerm>
-Turn <Emphasis>off</Emphasis> ``update-frame squeezing'' at garbage-collection
+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.)
</Sect2>
<Sect2 id="rts-hooks">
-<Title>``Hooks'' to change RTS behaviour
+<Title>“Hooks” to change RTS behaviour
</Title>
<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
+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>
-The function <Literal>defaultsHook</Literal><IndexTerm><Primary>defaultHook</Primary></IndexTerm> lets you change various
+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 <Literal>-H8m -K1m</Literal>:
+example, to set <Option>-H8m -K1m</Option>:
</Para>
<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 <Literal>ghc/rts/RtsFlags.h</Literal> the the GHC source tree.
+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
+“blows up,” e.g., on stack overflow. The hooks for these are as
follows:
</Para>
<VariableList>
<VarListEntry>
-<Term><Literal>void ErrorHdrHook (FILE *)</Literal>:</Term>
+<Term><Function>void ErrorHdrHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>ErrorHdrHook</Primary></IndexTerm>
-What's printed out before the message from <Literal>error</Literal>.
+What's printed out before the message from <Function>error</Function>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void OutOfHeapHook (unsigned long, unsigned long)</Literal>:</Term>
+<Term><Function>void OutOfHeapHook (unsigned long, unsigned long)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>OutOfHeapHook</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void StackOverflowHook (long int)</Literal>:</Term>
+<Term><Function>void StackOverflowHook (long int)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>StackOverflowHook</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void MallocFailHook (long int)</Literal>:</Term>
+<Term><Function>void MallocFailHook (long int)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>MallocFailHook</Primary></IndexTerm>
-The message printed if <Literal>malloc</Literal> fails.
+The message printed if <Function>malloc</Function> fails.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void PatErrorHdrHook (FILE *)</Literal>:</Term>
+<Term><Function>void PatErrorHdrHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>PatErrorHdrHook</Primary></IndexTerm>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void PreTraceHook (FILE *)</Literal>:</Term>
+<Term><Function>void PreTraceHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>PreTraceHook</Primary></IndexTerm>
-What's printed out before a <Literal>trace</Literal> message.
+What's printed out before a <Function>trace</Function> message.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>void PostTraceHook (FILE *)</Literal>:</Term>
+<Term><Function>void PostTraceHook (FILE *)</Function>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>PostTraceHook</Primary></IndexTerm>
-What's printed out after a <Literal>trace</Literal> message.
+What's printed out after a <Function>trace</Function> message.
</Para>
</ListItem>
</VarListEntry>
</Para>
<Para>
-For example, here is the ``hooks'' code used by GHC itself:
+For example, here is the “hooks” code used by GHC itself:
<ProgramListing>
#include <stdio.h>
</Sect2>
</Sect1>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff