X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=22ca59dcd25b1b1f0551bc427d8c00828b69072c;hb=4df9f0ee56ae232e1cf2f9531205af0dd916b496;hp=2b16234496a254dbcba699bb000f4c7cc50e0b42;hpb=f2b113c66ee688dc4249098c08a3dfab93b99f1d;p=ghc-hetmet.git
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 2b16234..22ca59d 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 set the -rtsopts flag appropriately 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
@@ -48,8 +49,8 @@
wraparound in the counters is your
fault!)
- Giving a +RTS -f
- RTS option option
+ Giving a +RTS -?
+ RTS option option
will print out the RTS options actually available in your program
(which vary, depending on how you compiled).
@@ -61,14 +62,16 @@
+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
+ If the -rtsopts flag is set to
+ something other than none 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 +131,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).
+
@@ -413,22 +425,88 @@
- size
+ sizeRTS option
- stack, minimum size
+ stack, initial size
- [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.
-
- The main thread is normally started with a slightly
- larger heap to cut down on unnecessary stack growth while
- the program is starting up.
-
+
+ [Default: 1k] Set the initial stack size for new
+ threads. (Note: this flag used to be
+ simply , but was renamed
+ to in GHC 7.2.1. The old name is
+ still accepted for backwards compatibility, but that may
+ be removed in a future version).
+
+
+
+ Thread stacks (including the main thread's stack) live on
+ the heap. As the stack grows, new stack chunks are added
+ as required; if the stack shrinks again, these extra stack
+ chunks are reclaimed by the garbage collector. The
+ default initial stack size is deliberately small, in order
+ to keep the time and space overhead for thread creation to
+ a minimum, and to make it practical to spawn threads for
+ even tiny pieces of work.
+
+
+
+
+
+
+ size
+ RTS
+ option
+ stackchunk size
+
+
+
+ [Default: 32k] Set the size of “stack
+ chunks”. When a thread's current stack overflows, a
+ new stack chunk is created and added to the thread's
+ stack, until the limit set by is
+ reached.
+
+
+
+ The advantage of smaller stack chunks is that the garbage
+ collector can avoid traversing stack chunks if they are
+ known to be unmodified since the last collection, so
+ reducing the chunk size means that the garbage collector
+ can identify more stack as unmodified, and the GC overhead
+ might be reduced. On the other hand, making stack chunks
+ too small adds some overhead as there will be more
+ overflow/underflow between chunks. The default setting of
+ 32k appears to be a reasonable compromise in most cases.
+
+
+
+
+
+
+ size
+ RTS
+ option
+ stackchunk buffer size
+
+
+
+ [Default: 1k] Sets the stack chunk buffer size.
+ When a stack chunk overflows and a new stack chunk is
+ created, some of the data from the previous stack chunk is
+ moved into the new chunk, to avoid an immediate underflow
+ and repeated overflow/underflow at the boundary. The
+ amount of stack moved is set by the
+ option.
+
+
+ Note that to avoid wasting space, this value should
+ typically be less than 10% of the size of a stack
+ chunk (), because in a chain of stack
+ chunks, each chunk will have a gap of unused space of this
+ size.
+
+
@@ -440,9 +518,14 @@
[Default: 8M] Set the maximum stack size for
an individual thread to size
- 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.
+ bytes. If the thread attempts to exceed this limit, it will
+ be send the StackOverflow exception.
+
+
+ This option is there mainly to stop the program eating up
+ all the available memory in the machine if it gets into an
+ infinite loop.
+
@@ -850,15 +933,16 @@
-
+
RTS option
Log events in binary format to the
file program.eventlog,
- where type indicates the type
- of events to log. Currently there is only one type
+ 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.
@@ -878,13 +962,19 @@
-
+ flagsRTS 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).
@@ -973,20 +1063,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
+ .
@@ -1045,6 +1128,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
@@ -1064,7 +1161,8 @@
The hook ghc_rts_optsghc_rts_optslets you set RTS
- options permanently for a given program. A common use for this is
+ options permanently for a given program, in the same way as the
+ newer linker option does. A common 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 -H128m
-K1m, place the following definition in a C source
@@ -1270,7 +1368,6 @@ $ ./a.out +RTS --info