RTS options actually available in your program (which vary, depending
on how you compiled).
+NOTE: to send RTS options to the compiler itself, you need to prefix
+the option with @-optCrts@, eg. to increase the maximum heap size for
+a compilation to 128M, you would add @-optCrts-M128m@ to the command
+line. The compiler understands some options directly without needing
+@-optCrts@: these are @-H@ and @-K@.
+
%************************************************************************
%* *
<sect2>RTS options to control the garbage-collector
<nidx>-A<size> RTS option</nidx>
<nidx>allocation area, size</nidx>
-[Default: 256k] Set the minimum (and initial) allocation area size
-used by the garbage collector. The allocation area is resized after
-each garbage collection to be a multiple of the size of the current
-live data (currently a factor of 2).
-
-Increasing the minimum allocation area size will typically give better
-performance for programs which quickly generate a large amount of live
-data.
+[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 <tt/-H/, below).
+
+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).
+
+With only 1 generation (<tt/-G1/) the <tt/-A/ 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
+<tt/-F/, below).
+
+<tag>@-F<factor>@:</tag>
+<nidx>-F<factor> RTS option</nidx>
+<nidx>heap size, factor</nidx>
+
+[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.
+
+The default seems to work well here. If you have plenty of memory, it
+is usually better to use <tt/-H<size>/ than to increase
+<tt/-F<factor>/.
+
+The <tt/-F/ setting will be automatically reduced by the garbage
+collector when the maximum heap size (the <tt/-M<size>/ setting)
+is approaching.
+
+<tag>@-G<generations>@:</tag>
+<nidx>-G<generations> RTS option</nidx>
+<nidx>generations, number of</nidx>
+
+[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
+<em/long/ time, because the oldest generation will never get
+collected.
+
+Specifying 1 generation with @+RTS -G1@ gives you a simple 2-space
+collector, as you would expect. In a 2-space collector, the @-A@
+option (see above) specifies the <em/minimum/ 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 <tt/-H/ option, see below).
+
+<tag>@-H<size>@:</tag>
+<nidx>-H<size> RTS option</nidx>
+<nidx>heap size, suggested</nidx>
+
+[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.
+
+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 <tt/-H<size>/. For
+improving GC performance, using <tt/-H<size>/ is usually a better
+bet than <tt/-A<size>/.
<tag>@-k<size>@:</tag>
<nidx>-k<size> RTS option</nidx>
%PostScript), using the @stat2resid@<nidx>stat2resid</nidx> utility in
%the GHC distribution (@ghc/utils/stat2resid@).
-<tag>@-F2s@:</tag>
-<nidx>-F2s RTS option</nidx>
-
-Forces a program compiled for generational GC to use two-space copying
-collection. The two-space collector may outperform the generational
-collector for programs which have a very low heap residency. It can
-also be used to generate a statistics file from which a basic heap
-residency profile can be produced (see Section <ref name="stat2resid -
-residency info from GC stats" id="stat2resid">).
-
-There will still be a small execution overhead imposed by the
-generational compilation as the test for old generation updates will
-still be executed (of course none will actually happen). This
-overhead is typically less than 1\%.
-
-<tag>@-j<size>@:</tag>
-<nidx>-j<size> RTS option</nidx>
-Force a major garbage collection every @<size>@ bytes. (Normally
-used because you're keen on getting major-GC stats, notably heap residency
-info.)
+% <tag>@-j<size>@:</tag>
+% <nidx>-j<size> RTS option</nidx>
+% Force a major garbage collection every @<size>@ bytes. (Normally
+% used because you're keen on getting major-GC stats, notably heap residency
+% info.)
</descrip>
``Ticky-ticky'' statistics are counts of various program actions
(updates, enters, etc.) The program must have been compiled using
-@-fstg-reduction-counts@<nidx>-fstg-reduction-counts option</nidx>
-(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.
+@-ticky@<nidx>-ticky option</nidx> (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 Section <ref name="Using ``ticky-ticky'' profiling
+(for implementors)" id="ticky-ticky">.
+
+<tag>@-xc@:</tag>
+<nidx>-xc RTS option</nidx>
+<nidx>cost centre display on exception</nidx>
+Display the current cost centre stack whenever an exception is
+raised. The program must have been compiled with profiling turned on:
+see Section <ref name="Profiling" id="profiling">. This feature is
+experimental; one day it will display the information only on
+<em>uncaught</em> exceptions.
<tag>@-D<num>@:</tag>
<nidx>-D RTS option</nidx>
bits are set in @<num>@. Only works if the RTS was compiled with the
@DEBUG@ option.
-<tag>@-N@:</tag>
-<nidx>-N RTS option</nidx>
-
-Normally, the garbage collector black-holes closures which are being
-evaluated, as a space-saving measure. This option turns off
-blackholing. You shouldn't ever need to use it.
-
-Historical note: this option used to be used to work around a problem
-with signal handling, where a signal handler might need to evaluate
-blackholed closures. Signal handlers are now run in a separate
-thread, and don't suffer from this problem.
+% Blackholing can't be turned off in new RTS --SDM
+%
+% <tag>@-N@:</tag>
+% <nidx>-N RTS option</nidx>
+%
+% Normally, the garbage collector black-holes closures which are being
+% evaluated, as a space-saving measure. This option turns off
+% blackholing. You shouldn't ever need to use it.
+%
+% Historical note: this option used to be used to work around a problem
+% with signal handling, where a signal handler might need to evaluate
+% blackholed closures. Signal handlers are now run in a separate
+% thread, and don't suffer from this problem.
<tag>@-Z@:</tag>
<nidx>-Z RTS option</nidx>
-Turn <em>off</em> ``update-frame squeezing'' at garbage-collection time.
-(There's no particularly good reason to turn it off.)
+Turn <em>off</em> ``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.)
</descrip>
%************************************************************************
{
fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
This is a compiler bug; please report it to
- glasgow-haskell-bugs@dcs.gla.ac.uk.\n\nFail: ");
+ glasgow-haskell-bugs@haskell.org.\n\nFail: ");
}
void
projects / ghc-hetmet.git / blobdiff