X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=defae2282316c98acb5f021e620bef09633c5657;hb=e5c3b478b3cd1707cf122833822f44b2ac09b8e9;hp=0e13f0e933154c02798762dbb52321bcf0276afc;hpb=f30d527344db528618f64a25250a3be557d9f287;p=ghc-hetmet.git diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index 0e13f0e..defae22 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: - 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 -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 <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 @@ -153,7 +329,7 @@ with a message like “failed to mmap() memory below 2Gb”. If you need to use this option to get GHCi working on your machine, please file a bug. - + On 64-bit machines, the RTS needs to allocate memory in the low 2Gb of the address space. Support for this across @@ -319,7 +495,7 @@ generation gen and higher. Omitting gen turns off the parallel GC completely, reverting to sequential GC. - + The default parallel GC settings are usually suitable for parallel programs (i.e. those using par, Strategies, or with multiple @@ -333,7 +509,7 @@ restrict parallel GC to the old generation with -qg1. - + @@ -348,7 +524,7 @@ 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 @@ -641,7 +817,7 @@ - The peak memory the RTS has allocated from the OS. + The peak memory the RTS has allocated from the OS. @@ -836,12 +1012,12 @@ - How many page faults occured this garbage collection. + How many page faults occurred this garbage collection. - How many page faults occured since the end of the last garbage + How many page faults occurred since the end of the last garbage collection. @@ -1033,7 +1209,7 @@ - An RTS debugging flag; only availble if the program was + An RTS debugging flag; only available if the program was linked with the option. Various values of x are provided to enable debug messages and additional runtime sanity checks @@ -1128,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 RTS RTS