[project @ 1999-11-29 12:02:42 by keithw]

[ghc-hetmet.git] / ghc / docs / users_guide / runtime_control.vsgml

diff --git a/ghc/docs/users_guide/runtime_control.vsgml b/ghc/docs/users_guide/runtime_control.vsgml
index 19967ec..04caf42 100644 (file)
--- a/ghc/docs/users_guide/runtime_control.vsgml
+++ b/ghc/docs/users_guide/runtime_control.vsgml
@@ -48,6 +48,12 @@ Giving a @+RTS -f@<nidx>-f RTS option</nidx> option will print out the
 RTS options actually available in your program (which vary, depending
 on how you compiled).
 
 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
 %************************************************************************
 %*                                                                      *
 <sect2>RTS options to control the garbage-collector

@@ -67,14 +73,70 @@ maximum performance.
 <nidx>-A&lt;size&gt; RTS option</nidx>
 <nidx>allocation area, size</nidx>
 
 <nidx>-A&lt;size&gt; 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&lt;factor&gt; 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&lt;size&gt;/ than to increase
+<tt/-F&lt;factor&gt;/.
+
+The <tt/-F/ setting will be automatically reduced by the garbage
+collector when the maximum heap size (the <tt/-M&lt;size&gt;/ setting)
+is approaching.
+
+<tag>@-G<generations>@:</tag>
+<nidx>-G&lt;generations&gt; 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&lt;size&gt; 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&lt;size&gt/.  For
+improving GC performance, using <tt/-H&lt;size&gt/ is usually a better
+bet than <tt/-A&lt;size&gt/.

 
 <tag>@-k<size>@:</tag>
 <nidx>-k&lt;size&gt; RTS option</nidx>
 
 <tag>@-k<size>@:</tag>
 <nidx>-k&lt;size&gt; RTS option</nidx>

@@ -132,26 +194,11 @@ heap size based on the current amount of live data.
 %PostScript), using the @stat2resid@<nidx>stat2resid</nidx> utility in
 %the GHC distribution (@ghc/utils/stat2resid@).
 
 %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&lt;size&gt; 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&lt;size&gt; 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>
 
 
 </descrip>
 

@@ -201,11 +248,21 @@ The @<file>@ business works just like on the @-S@ RTS option (above).
 
 ``Ticky-ticky'' statistics are counts of various program actions
 (updates, enters, etc.)  The program must have been compiled using
 
 ``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>
 
 <tag>@-D<num>@:</tag>
 <nidx>-D RTS option</nidx>

@@ -213,22 +270,26 @@ An RTS debugging flag; varying quantities of output depending on which
 bits are set in @<num>@.  Only works if the RTS was compiled with the
 @DEBUG@ option.
 
 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>
 
 <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>
 
 %************************************************************************
 </descrip>
 
 %************************************************************************

@@ -336,7 +397,7 @@ PatErrorHdrHook (FILE *where)
 {
     fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
        This is a compiler bug; please report it to
 {
     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
 }
 
 void