From: Simon Marlow Date: Thu, 16 Dec 2010 12:31:51 +0000 (+0000) Subject: refactor and tidy up the section on RTS options X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=be36dc8301313715f1373a323c9c322f57295e74 refactor and tidy up the section on RTS options --- diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml index adaf370..b48ebe8 100644 --- a/docs/users_guide/phases.xml +++ b/docs/users_guide/phases.xml @@ -1000,31 +1000,53 @@ $ cat foo.hspp on the command line or via the GHCRTS environment variable. There are three possibilities: - - - disables all processing of RTS options. - Passing anywhere on the command line causes the program - to abort with an error message. Setting the GHCRTS environment - variable causes a warning is printed before the main Haskell program runs. - - - enables only the "safe" RTS options on the - command line. (Currently only and .) - Any other RTS options on the command line abort the program with an error - message. All RTS options in the GHCRTS environment variable are - processed as normal. This is the default setting. - - - (or just ) enables - all RTS option processing, both on the command line and - through the GHCRTS environment variable. - - + + + + + + Disable all processing of RTS options. + If appears anywhere on the command + line, then the program will abort with an error message. + If the GHCRTS environment variable is + set, then the program will emit a warning message, + GHCRTS will be ignored, and the program + will run as normal. + + + + + + + [this is the default setting] Enable + only the "safe" RTS options: (Currently + only + and .) Any other RTS options + on the command line or in the GHCRTS + environment variable causes the program with to abort + with an error message. + + + + + , or + just + + + Enable all RTS option + processing, both on the command line and through + the GHCRTS environment variable. + + + + - Prior to GHC 7.0, the default was to process all RTS options. However, since - RTS options can be used to write logging data to arbitrary files under the - security context of the running program, there is a potential security problem. - For this reason, GHC 7.0 defaults to . + In GHC 6.12.3 and earlier, the default was to process all + RTS options. However, since RTS options can be used to + write logging data to arbitrary files under the security + context of the running program, there is a potential + security problem. For this reason, GHC 7.0.1 and later + default to . @@ -1038,7 +1060,7 @@ $ cat foo.hspp This option allows you to set the default RTS options at link-time. For example, sets the default heap size to 128MB. - This will now always be the default heap size, unless the user overrides it. + This will always be the default heap size for this program, unless the user overrides it. (Depending on the setting of the option, the user might not have the ability to change RTS options at run-time, in which case would be the only way to set diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index 22ca59d..045ea07 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -1,5 +1,5 @@ - +
Running a compiled program runtime control of Haskell programs @@ -8,87 +8,262 @@ 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 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. + + There are four ways to set RTS options: - When your Haskell program starts up, its RTS extracts - command-line arguments bracketed between - - and - - as its own. For example: + + + + 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 + () + + + + + +
+ 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 -? - 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 - - 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 - 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 <envar>GHCRTS</envar> + 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 @@ -172,9 +347,9 @@ - +
- +
RTS options to control the garbage collector garbage collectoroptions @@ -857,17 +1032,17 @@ - +
- +
RTS options for concurrency and parallelism The RTS options related to concurrency are described in , and those for parallelism in . - +
- +
RTS options for profiling Most profiling runtime options are only available when you @@ -898,9 +1073,9 @@ - +
- +
Tracing tracing @@ -991,9 +1166,9 @@ the binary eventlog file by using the option. - +
- +
RTS options for hackers, debuggers, and over-interested souls @@ -1126,104 +1301,9 @@ - - - - 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, 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. - +
- +
Getting information about the RTS RTS @@ -1363,8 +1443,8 @@ $ ./a.out +RTS --info - - +
+