X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=725ee887dd622c684cdd915cefd002567a8a5a25;hb=949ce3bb4ef2654a814b3549051e439daf82b5e9;hp=995e26302dda2c2a7d4cdf224c6c841849f3fd41;hpb=071367ea146fa1622e2e533fc9cf804c2be14a57;p=ghc-hetmet.git diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index 995e263..725ee88 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -85,6 +85,54 @@ + + Miscellaneous RTS options + + + + + RTS + option + + Sets the interval that the RTS clock ticks at. The + runtime uses a single timer signal to count ticks; this timer + signal is used to control the context switch timer () and the heap profiling + timer . Also, the + time profiler uses the RTS timer signal directly to record + time profiling samples. + + Normally, setting the option + directly is not necessary: the resolution of the RTS timer is + adjusted automatically if a short interval is requested with + the or options. + However, setting is required in order to + increase the resolution of the time profiler. + + Using a value of zero disables the RTS clock + completely, and has the effect of disabling timers that + depend on it: the context switch timer and the heap profiling + timer. Context switches will still happen, but + deterministically and at a rate much faster than normal. + Disabling the interval timer is useful for debugging, because + it eliminates a source of non-determinism at runtime. + + + + + + RTS + option + + If yes (the default), the RTS installs signal handlers to catch + 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. + + + + + RTS options to control the garbage collector @@ -220,6 +268,43 @@ + + threads + RTS option + + + [Default: 1] [new in GHC 6.10] Set the number + of threads to use for garbage collection. This option is + only accepted when the program was linked with the + option; see . + + The garbage collector is able to work in parallel when + given more than one OS thread. Experiments have shown + that this 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. + + This value is set automatically when the + option is used, so the only reason to + use would be if you wanted to use a + different number of threads for GC than for execution. + For example, if your program is strictly single-threaded + but you still want to benefit from parallel GC, then it + might make sense to use rather than + . + + + + size RTS option @@ -351,46 +436,35 @@ + + file + RTS option + - file + file RTS option - file + file RTS option - Write modest () or verbose - () garbage-collector statistics into file - file. The default - file is - program.stat. The - file stderr - is treated specially, with the output really being sent to - stderr. - - This option is useful for watching how the storage - manager adjusts the heap size based on the current amount of - live data. - - + These options produce runtime-system statistics, such + as the amount of time spent executing the program and in the + garbage collector, the amount of memory allocated, the + maximum size of the heap, and so on. The three + variants give different levels of detail: + produces a single line of output in the + same format as GHC's option, + produces a more detailed summary at the + end of the program, and additionally + produces information about each and every garbage + collection. - - - - RTS option - - - Write a one-line GC stats summary after running the - program. This output is in the same format as that produced - by the option. - - As with , the default - file is - program.stat. The - file stderr - is treated specially, with the output really being sent to - stderr. + The output is placed in + file. If + file is omitted, then the output + is sent to stderr. @@ -398,11 +472,12 @@ - RTS options for profiling and Concurrent/Parallel Haskell + RTS options for profiling and parallelism The RTS options related to profiling are described in ; and those for concurrent/parallel - stuff, in . + linkend="rts-options-heap-prof"/>, those for concurrency in + , and those for parallelism in + . @@ -612,6 +687,29 @@ char *ghc_rts_opts = "-H128m -K1m"; ghc/compiler/parser/hschooks.c in a GHC source tree. + + + Getting information about the RTS + + RTS + + It is possible to ask the RTS to give some information about + itself. To do this, use the flag, e.g. + +$ ./a.out +RTS --info + [("GHC RTS", "Yes") + ,("GHC version", "6.7") + ,("RTS way", "rts_p") + ,("Host platform", "x86_64-unknown-linux") + ,("Build platform", "x86_64-unknown-linux") + ,("Target platform", "x86_64-unknown-linux") + ,("Compiler unregisterised", "NO") + ,("Tables next to code", "YES") + ] + + The information is formatted such that it can be read as a + of type [(String, String)]. +