X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=be341b220dde554fc9c1061369bd431dab15debd;hb=478e69b303eb2e653a2ebf5c888b5efdfef1fb9d;hp=9ef32a81c0414799d751a4a6bed6111f6f219af2;hpb=f61baf76c9fa20aa972938384887bcb52151e76f;p=ghc-hetmet.git
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 9ef32a8..be341b2 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -8,84 +8,260 @@
To make an executable program, the GHC system compiles your
code and then links it with a non-trivial runtime system (RTS),
- which handles storage management, profiling, etc.
+ which handles storage management, thread scheduling, profiling, and
+ so on.
+
+
+ The RTS has a lot of options to control its behaviour. For
+ example, you can change the context-switch interval, the default
+ size of the heap, and enable heap profiling. These options can be
+ passed to the runtime system in a variety of different ways; the
+ next section () describes
+ the various methods, and the following sections describe the RTS
+ options themselves.
+
+
+
+ Setting RTS options
+ RTS options, setting
- 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.
+
+ There are four ways to set RTS options:
+
+
+
+
+ on the command line between +RTS ... -RTS, when running the program
+ ()
+
+
+
+ at compile-time, using
+ ()
+
+
+
+ with the environment variable GHCRTS
+ ()
+
+
+
+ by overriding “hooks” in the runtime system
+ ()
+
+
+
+
- When your Haskell program starts up, its RTS extracts
- command-line arguments bracketed between
-
- and
-
- as its own. For example:
+
+ Setting RTS options on the command line
+
+
+ If you set the -rtsopts flag appropriately
+ when linking (see ), you can
+ give RTS options on the command line when running your
+ program.
+
+
+
+ When your Haskell program starts up, the RTS extracts
+ command-line arguments bracketed between
+
+ and
+
+ as its own. For example:
+
-% ./a.out -f +RTS -p -S -RTS -h foo bar
+$ ghc prog.hs -rtsopts
+[1 of 1] Compiling Main ( prog.hs, prog.o )
+Linking prog ...
+$ ./prog -f +RTS -H32m -S -RTS -h foo bar
- The RTS will snaffle
- for itself, and the remaining arguments -f -h foo bar
- will be handed to your program if/when it calls
- System.getArgs.
+
+ The RTS will
+ snaffle for itself,
+ and the remaining arguments -f -h foo bar
+ will be available to your program if/when it calls
+ System.Environment.getArgs.
+
- No option is required if the
- runtime-system options extend to the end of the command line, as in
- this example:
+
+ No option is required if the
+ runtime-system options extend to the end of the command line, as in
+ this example:
+
% hls -ltr /usr/etc +RTS -A5m
- 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
- .
-
- As always, for RTS options that take
- sizes: If the last character of
- size is a K or k, multiply by 1000; if an
- M or m, by 1,000,000; if a G or G, by 1,000,000,000. (And any
- wraparound in the counters is your
- fault!)
-
- Giving a +RTS -f
- RTS option option
- will print out the RTS options actually available in your program
- (which vary, depending on how you compiled).
-
- NOTE: since GHC is itself compiled by GHC, you can change RTS
- options in the compiler using the normal
- +RTS ... -RTS
- combination. eg. to increase the maximum heap
- size for a compilation to 128M, you would add
- +RTS -M128m -RTS
- to the command line.
-
-
- Setting global RTS options
-
- RTS optionsfrom the environment
- environment variablefor
- setting RTS options
-
- 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
- sh-like shell):
+
+ 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
+ .
+
+
+
+ As always, for RTS options that take
+ sizes: If the last character of
+ size is a K or k, multiply by 1000; if an
+ M or m, by 1,000,000; if a G or G, by 1,000,000,000. (And any
+ wraparound in the counters is your
+ fault!)
+
+
+
+ Giving a +RTS -?
+ RTS option option
+ will print out the RTS options actually available in your program
+ (which vary, depending on how you compiled).
+
+
+ NOTE: since GHC is itself compiled by GHC, you can change RTS
+ options in the compiler using the normal
+ +RTS ... -RTS
+ combination. eg. to set the maximum heap
+ size for a compilation to 128M, you would add
+ +RTS -M128m -RTS
+ to the command line.
+
+
+
+
+ Setting RTS options at compile time
+
+
+ GHC lets you change the default RTS options for a program at
+ compile time, using the -with-rtsopts
+ flag (). For example, to
+ set -H128m -K64m, link
+ with -with-rtsopts="-H128m -K64m".
+
+
+
+
+ Setting RTS options with the GHCRTS
+ environment variable
+
+ RTS optionsfrom the environment
+ environment variablefor
+ setting RTS options
+
+
+ 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 2G for all GHC-compiled programs (using an
+ sh-like shell):
+
- GHCRTS='-M128m'
+ GHCRTS='-M2G'
export GHCRTS
- RTS options taken from the GHCRTS environment
- variable can be overridden by options given on the command
- line.
+
+ RTS options taken from the GHCRTS environment
+ variable can be overridden by options given on the command
+ line.
+
-
+
+ Tip: setting something like GHCRTS=-M2G
+ in your environment is a handy way to avoid Haskell programs
+ growing beyond the real memory in your machine, which is
+ easy to do by accident and can cause the machine to slow to
+ a crawl until the OS decides to kill the process (and you
+ hope it kills the right one).
+
+
+
+
+ “Hooks” to change RTS behaviour
+
+ hooksRTS
+ RTS hooks
+ RTS behaviour, changing
+
+ GHC lets you exercise rudimentary control over the RTS
+ settings for 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.
+
+ Owing to the vagaries of DLL linking, these hooks don't work
+ under Windows when the program is built dynamically.
+
+ The hook ghc_rts_optsghc_rts_opts
+ lets you set RTS
+ 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
+ file:
+
+
+char *ghc_rts_opts = "-H128m -K1m";
+
+
+ Compile the C file, and include the object file on the
+ command line when you link your Haskell program.
+
+ These flags are interpreted first, before any RTS flags from
+ the GHCRTS environment variable and any flags
+ on the command line.
+
+ You can also change the messages printed when the runtime
+ system “blows up,” e.g., on stack overflow. The hooks
+ for these are as follows:
+
+
+
+
+
+ void OutOfHeapHook (unsigned long, unsigned long)
+ OutOfHeapHook
+
+
+ The heap-overflow message.
+
+
+
+
+
+ void StackOverflowHook (long int)
+ StackOverflowHook
+
+
+ The stack-overflow message.
+
+
+
+
+
+ void MallocFailHook (long int)
+ MallocFailHook
+
+
+ The message printed if malloc
+ fails.
+
+
+
+
+ For examples of the use of these hooks, see GHC's own
+ versions in the file
+ ghc/compiler/parser/hschooks.c in a GHC
+ source tree.
+
+
+
Miscellaneous RTS options
@@ -424,22 +600,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.
+
+
@@ -451,9 +693,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.
+
@@ -1057,100 +1304,6 @@
- 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
-
- hooksRTS
- RTS hooks
- RTS behaviour, changing
-
- GHC lets you exercise rudimentary control over the RTS
- settings for 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.
-
- Owing to the vagaries of DLL linking, these hooks don't work
- under Windows when the program is built dynamically.
-
- The hook ghc_rts_optsghc_rts_opts
- lets you set RTS
- options permanently for a given program. 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
- file:
-
-
-char *ghc_rts_opts = "-H128m -K1m";
-
-
- Compile the C file, and include the object file on the
- command line when you link your Haskell program.
-
- These flags are interpreted first, before any RTS flags from
- the GHCRTS environment variable and any flags
- on the command line.
-
- You can also change the messages printed when the runtime
- system “blows up,” e.g., on stack overflow. The hooks
- for these are as follows:
-
-
-
-
-
- void OutOfHeapHook (unsigned long, unsigned long)
- OutOfHeapHook
-
-
- The heap-overflow message.
-
-
-
-
-
- void StackOverflowHook (long int)
- StackOverflowHook
-
-
- The stack-overflow message.
-
-
-
-
-
- void MallocFailHook (long int)
- MallocFailHook
-
-
- The message printed if malloc
- fails.
-
-
-
-
- For examples of the use of these hooks, see GHC's own
- versions in the file
- ghc/compiler/parser/hschooks.c in a GHC
- source tree.
-
-
- Getting information about the RTSRTS