X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=40409131cc3729d829a53c329d5b7453554e6305;hb=73855b2d99dfb60b89c057f43ab313b243cfc574;hp=69e26bc9208ea67c35b1a81d01e065f05a459324;hpb=9ee105bd1f977a8fd68281e7658383d5a0c86156;p=ghc-hetmet.git
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 69e26bc..4040913 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -10,7 +10,8 @@
code and then links it with a non-trivial runtime system (RTS),
which handles storage management, profiling, etc.
- You have some control over the behaviour of the RTS, by giving
+ If you use the -rtsopts flag when linking,
+ you have some control over the behaviour of the RTS, by giving
special command-line arguments to your program.When your Haskell program starts up, its RTS extracts
@@ -61,14 +62,15 @@
+RTS -M128m -RTS
to the command line.
-
+ Setting global RTS optionsRTS optionsfrom the environmentenvironment variablefor
setting RTS options
- RTS options are also taken from the environment variable
+ When the -rtsopts flag is used when linking,
+ RTS options are also taken from the environment variable
GHCRTSGHCRTS. For example, to set the maximum heap size
to 128M for all GHC-compiled programs (using an
@@ -128,6 +130,15 @@
things like ctrl-C. This option is primarily useful for when
you are using the Haskell code as a DLL, and want to set your
own signal handlers.
+
+ Note that even
+ with , the RTS
+ interval timer signal is still enabled. The timer signal
+ is either SIGVTALRM or SIGALRM, depending on the RTS
+ configuration and OS capabilities. To disable the timer
+ signal, use the -V0 RTS option (see
+ above).
+
@@ -298,51 +309,58 @@
-
- RTS
+
+ RTS
option
- [New in GHC 6.12.1] Disable the parallel GC.
- The parallel GC is turned on automatically when parallel
- execution is enabled with the option;
- this option is available to turn it off if
- necessary.
+ [New in GHC 6.12.1] [Default: 0]
+ Use parallel GC in
+ generation gen and higher.
+ Omitting gen turns off the
+ parallel GC completely, reverting to sequential GC.
- Experiments have shown that parallel GC usually
- results in a performance improvement given 3 cores or
- more; with 2 cores it may or may not be beneficial,
- depending on the workload. Bigger heaps work better with
- parallel GC, so set your value high (3
- or more times the maximum residency). Look at the timing
- stats with to see whether you're
- getting any benefit from parallel GC or not. If you find
- parallel GC is significantly slower
- (in elapsed time) than sequential GC, please report it as
- a bug.
-
- In GHC 6.10.1 it was possible to use a different
- number of threads for GC than for execution, because the GC
- used its own pool of threads. Now, the GC uses the same
- threads as the mutator (for executing the program).
+ The default parallel GC settings are usually suitable
+ for parallel programs (i.e. those
+ using par, Strategies, or with multiple
+ threads). However, it is sometimes beneficial to enable
+ the parallel GC for a single-threaded sequential program
+ too, especially if the program has a large amount of heap
+ data and GC is a significant fraction of runtime. To use
+ the parallel GC in a sequential program, enable the
+ parallel runtime with a suitable -N
+ option, and additionally it might be beneficial to
+ restrict parallel GC to the old generation
+ with -qg1.
-
- RTS
+
+ RTS
option
- [Default: 1] [New in GHC 6.12.1]
- Enable the parallel GC only in
- generation n and greater.
- Parallel GC is often not worthwhile for collections in
- generation 0 (the young generation), so it is enabled by
- default only for collections in generation 1 (and higher,
- if applicable).
+ [New in GHC 6.12.1] [Default: 1] Use
+ load-balancing in the parallel GC in
+ generation gen and higher.
+ Omitting gen disables
+ load-balancing entirely.
+
+
+ Load-balancing shares out the work of GC between the
+ available cores. This is a good idea when the heap is
+ large and we need to parallelise the GC work, however it
+ is also pessimal for the short young-generation
+ collections in a parallel program, because it can harm
+ locality by moving data from the cache of the CPU where is
+ it being used to the cache of another CPU. Hence the
+ default is to do load-balancing only in the
+ old-generation. In fact, for a parallel program it is
+ sometimes beneficial to disable load-balancing entirely
+ with -qb.
@@ -810,6 +828,99 @@
+
+ Tracing
+
+ tracing
+ events
+ eventlog files
+
+
+ When the program is linked with the
+ option (), runtime events can
+ be logged in two ways:
+
+
+
+
+
+ In binary format to a file for later analysis by a
+ variety of tools. One such tool
+ is ThreadScopeThreadScope,
+ which interprets the event log to produce a visual parallel
+ execution profile of the program.
+
+
+
+
+ As text to standard output, for debugging purposes.
+
+
+
+
+
+
+
+
+ RTS option
+
+
+
+ Log events in binary format to the
+ file program.eventlog,
+ where flags is a sequence of
+ zero or more characters indicating which kinds of events
+ to log. Currently there is only one type
+ supported: -ls, for scheduler events.
+
+
+
+ The format of the log file is described by the header
+ EventLogFormat.h that comes with
+ GHC, and it can be parsed in Haskell using
+ the ghc-events
+ library. To dump the contents of
+ a .eventlog file as text, use the
+ tool show-ghc-events that comes with
+ the ghc-events
+ package.
+
+
+
+
+
+
+ flags
+ RTS option
+
+
+
+ Log events as text to standard output, instead of to
+ the .eventlog file.
+ The flags are the same as
+ for , with the additional
+ option t which indicates that the
+ each event printed should be preceded by a timestamp value
+ (in the binary .eventlog file, all
+ events are automatically associated with a timestamp).
+
+
+
+
+
+
+
+ The debugging
+ options also
+ generate events which are logged using the tracing framework.
+ By default those events are dumped as text to stdout
+ (
+ implies ), but they may instead be stored in
+ the binary eventlog file by using the
+ option.
+
+
+
RTS options for hackers, debuggers, and over-interested
souls
@@ -846,14 +957,28 @@
- num
+ x-DRTS option
- 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 option.
+
+ An RTS debugging flag; only availble if the program was
+ linked with the option. Various
+ values of x are provided to
+ enable debug messages and additional runtime sanity checks
+ in different subsystems in the RTS, for
+ example +RTS -Ds -RTS enables debug
+ messages from the scheduler.
+ Use +RTS -? to find out which
+ debug flags are supported.
+
+
+
+ Debug messages will be sent to the binary event log file
+ instead of stdout if the option is
+ added. This might be useful for reducing the overhead of
+ debug tracing.
+
@@ -866,20 +991,13 @@
Produce “ticky-ticky” statistics at the
- end of the program run. The file
- business works just like on the RTS
- option (above).
-
- “Ticky-ticky” statistics are counts of
- various program actions (updates, enters, etc.) The program
- must have been compiled using
-
- (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 .
+ end of the program run (only available if the program was
+ linked with ).
+ The file business works just like
+ on the RTS option, above.
+
+ For more information on ticky-ticky profiling, see
+ .
@@ -938,6 +1056,20 @@
+
+ Linker flags to change RTS behaviour
+
+ RTS behaviour, changing
+
+
+ GHC lets you exercise rudimentary control over the RTS settings
+ for any given program, by using the -with-rtsopts
+ linker flag. For example, to set -H128m -K1m,
+ link with -with-rtsopts="-H128m -K1m".
+
+
+
+
“Hooks” to change RTS behaviour
@@ -1163,7 +1295,6 @@ $ ./a.out +RTS --info