X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=be341b220dde554fc9c1061369bd431dab15debd;hb=d73c1bce81d47da67c20eef3fb22e68c14b380aa;hp=183cd9cb59975fa9cd00abbee958f9dc8a924beb;hpb=c0c81d098a7637ac79c7309e64166c1d8b005027;p=ghc-hetmet.git diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index 183cd9c..be341b2 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -8,82 +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. - - 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 - command-line arguments bracketed between - - and - - as its own. For example: + 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 + + + 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 + () + + + + + + + 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 - - 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 @@ -128,6 +306,44 @@ 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). + + + + + + + RTS + option + + + WARNING: this option is for working around memory + allocation problems only. Do not use unless GHCi fails + 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 + different operating systems is patchy, and sometimes fails. + This option is there to give the RTS a hint about where it + should be able to allocate memory in the low 2Gb of the + address space. For example, +RTS -xm20000000 + -RTS would hint that the RTS should allocate + starting at the 0.5Gb mark. The default is to use the OS's + built-in support for allocating memory in the low 2Gb if + available (e.g. mmap + with MAP_32BIT on Linux), or + otherwise -xm40000000. + @@ -153,7 +369,7 @@ allocation area, size - [Default: 256k] Set the allocation area size + [Default: 512k] Set the allocation area size used by the garbage collector. The allocation area (actually generation 0 step 0) is fixed and is never resized (unless you use , below). @@ -269,38 +485,59 @@ - threads - RTS option + + 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 - . + [New in GHC 6.12.1] [Default: 0] + Use parallel GC in + 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 + threads). However, it is sometimes beneficial to enable + the parallel GC for a single-threaded sequential program + too, especially if the program has a large amount of heap + data and GC is a significant fraction of runtime. To use + the parallel GC in a sequential program, enable the + parallel runtime with a suitable -N + option, and additionally it might be beneficial to + restrict parallel GC to the old generation + with -qg1. + + + + + + + RTS + option + + + + [New in GHC 6.12.1] [Default: 1] Use + load-balancing in the parallel GC in + 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 + large and we need to parallelise the GC work, however it + is also pessimal for the short young-generation + collections in a parallel program, because it can harm + locality by moving data from the cache of the CPU where is + it being used to the cache of another CPU. Hence the + default is to do load-balancing only in the + old-generation. In fact, for a parallel program it is + sometimes beneficial to disable load-balancing entirely + with -qb. + @@ -363,22 +600,88 @@ - size + size RTS 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. + + @@ -390,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. + @@ -436,46 +744,290 @@ + + 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. - - - - - - RTS option + + 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. + 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. + + The output is placed in + file. If + file is omitted, then the output + is sent to stderr. + + + If you use the -t flag then, when your + program finishes, you will see something like this: + + + +<<ghc: 36169392 bytes, 69 GCs, 603392/1065272 avg/max bytes residency (2 samples), 3M in use, 0.00 INIT (0.00 elapsed), 0.02 MUT (0.02 elapsed), 0.07 GC (0.07 elapsed) :ghc>> + + + + This tells you: + + + + + + The total number of bytes allocated by the program over the + whole run. + + + + + The total number of garbage collections performed. + + + + + The average and maximum "residency", which is the amount of + live data in bytes. The runtime can only determine the + amount of live data during a major GC, which is why the + number of samples corresponds to the number of major GCs + (and is usually relatively small). To get a better picture + of the heap profile of your program, use + the RTS option + (). + + + + + The peak memory the RTS has allocated from the OS. + + + + + The amount of CPU time and elapsed wall clock time while + initialising the runtime system (INIT), running the program + itself (MUT, the mutator), and garbage collecting (GC). + + + + + + You can also get this in a more future-proof, machine readable + format, with -t --machine-readable: + + + + [("bytes allocated", "36169392") + ,("num_GCs", "69") + ,("average_bytes_used", "603392") + ,("max_bytes_used", "1065272") + ,("num_byte_usage_samples", "2") + ,("peak_megabytes_allocated", "3") + ,("init_cpu_seconds", "0.00") + ,("init_wall_seconds", "0.00") + ,("mutator_cpu_seconds", "0.02") + ,("mutator_wall_seconds", "0.02") + ,("GC_cpu_seconds", "0.07") + ,("GC_wall_seconds", "0.07") + ] + + + + If you use the -s flag then, when your + program finishes, you will see something like this (the exact + details will vary depending on what sort of RTS you have, e.g. + you will only see profiling data if your RTS is compiled for + profiling): + + + + 36,169,392 bytes allocated in the heap + 4,057,632 bytes copied during GC + 1,065,272 bytes maximum residency (2 sample(s)) + 54,312 bytes maximum slop + 3 MB total memory in use (0 MB lost due to fragmentation) + + Generation 0: 67 collections, 0 parallel, 0.04s, 0.03s elapsed + Generation 1: 2 collections, 0 parallel, 0.03s, 0.04s elapsed + + SPARKS: 359207 (557 converted, 149591 pruned) + + INIT time 0.00s ( 0.00s elapsed) + MUT time 0.01s ( 0.02s elapsed) + GC time 0.07s ( 0.07s elapsed) + EXIT time 0.00s ( 0.00s elapsed) + Total time 0.08s ( 0.09s elapsed) + + %GC time 89.5% (75.3% elapsed) + + Alloc rate 4,520,608,923 bytes per MUT second + + Productivity 10.5% of total user, 9.1% of total elapsed + + + + + + The "bytes allocated in the heap" is the total bytes allocated + by the program over the whole run. + + + + + GHC uses a copying garbage collector by default. "bytes copied + during GC" tells you how many bytes it had to copy during + garbage collection. + + + + + The maximum space actually used by your program is the + "bytes maximum residency" figure. This is only checked during + major garbage collections, so it is only an approximation; + the number of samples tells you how many times it is checked. + + + + + The "bytes maximum slop" tells you the most space that is ever + wasted due to the way GHC allocates memory in blocks. Slop is + memory at the end of a block that was wasted. There's no way + to control this; we just like to see how much memory is being + lost this way. + + + + + The "total memory in use" tells you the peak memory the RTS has + allocated from the OS. + + + + + Next there is information about the garbage collections done. + For each generation it says how many garbage collections were + done, how many of those collections were done in parallel, + the total CPU time used for garbage collecting that generation, + and the total wall clock time elapsed while garbage collecting + that generation. + + + + The SPARKS statistic refers to the + use of Control.Parallel.par and related + functionality in the program. Each spark represents a call + to par; a spark is "converted" when it is + executed in parallel; and a spark is "pruned" when it is + found to be already evaluated and is discarded from the pool + by the garbage collector. Any remaining sparks are + discarded at the end of execution, so "converted" plus + "pruned" does not necessarily add up to the total. + + + + Next there is the CPU time and wall clock time elapsed broken + down by what the runtime system was doing at the time. + INIT is the runtime system initialisation. + MUT is the mutator time, i.e. the time spent actually running + your code. + GC is the time spent doing garbage collection. + RP is the time spent doing retainer profiling. + PROF is the time spent doing other profiling. + EXIT is the runtime system shutdown time. + And finally, Total is, of course, the total. + + + %GC time tells you what percentage GC is of Total. + "Alloc rate" tells you the "bytes allocated in the heap" divided + by the MUT CPU time. + "Productivity" tells you what percentage of the Total CPU and wall + clock elapsed times are spent in the mutator (MUT). + + + + + + The -S flag, as well as giving the same + output as the -s flag, prints information + about each GC as it happens: + + + + Alloc Copied Live GC GC TOT TOT Page Flts + bytes bytes bytes user elap user elap + 528496 47728 141512 0.01 0.02 0.02 0.02 0 0 (Gen: 1) +[...] + 524944 175944 1726384 0.00 0.00 0.08 0.11 0 0 (Gen: 0) + + + + For each garbage collection, we print: + + + + + + How many bytes we allocated this garbage collection. + + + + + How many bytes we copied this garbage collection. + + + + + How many bytes are currently live. + + + + + How long this garbage collection took (CPU time and elapsed + wall clock time). + + + + + How long the program has been running (CPU time and elapsed + wall clock time). + + + + + How many page faults occured this garbage collection. + + + + + How many page faults occured since the end of the last garbage + collection. + + + + + Which generation is being garbage collected. + + + + @@ -483,14 +1035,139 @@ - RTS options for profiling and parallelism + RTS options for concurrency and parallelism - The RTS options related to profiling are described in , those for concurrency in + 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 + compile your program for profiling (see + , and + for the runtime options). + However, there is one profiling option that is available + for ordinary non-profiled executables: + + + + + + RTS + option + + + Generates a basic heap profile, in the + file prog.hp. + To produce the heap profile graph, + use hp2ps (see ). The basic heap profile is broken down by data + constructor, with other types of closures (functions, thunks, + etc.) grouped into broad categories + (e.g. FUN, THUNK). To + get a more detailed profile, use the full profiling + support (). + + + + + + + Tracing + + tracing + events + eventlog files + + + When the program is linked with the + option (), runtime events can + be logged in two ways: + + + + + + In binary format to a file for later analysis by a + variety of tools. One such tool + is ThreadScopeThreadScope, + which interprets the event log to produce a visual parallel + execution profile of the program. + + + + + As text to standard output, for debugging purposes. + + + + + + + + + RTS option + + + + Log events in binary format to the + file program.eventlog, + 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. + + + + The format of the log file is described by the header + EventLogFormat.h that comes with + GHC, and it can be parsed in Haskell using + the ghc-events + library. To dump the contents of + a .eventlog file as text, use the + tool show-ghc-events that comes with + the ghc-events + package. + + + + + + + flags + RTS 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). + + + + + + + + The debugging + options also + generate events which are logged using the tracing framework. + By default those events are dumped as text to stdout + ( + implies ), but they may instead be stored in + the binary eventlog file by using the + option. + + + RTS options for hackers, debuggers, and over-interested souls @@ -527,14 +1204,28 @@ - num + x -DRTS option - An RTS debugging flag; varying quantities of output - depending on which bits are set in - num. Only works if the RTS was - compiled with the option. + + An RTS debugging flag; only availble if the program was + linked with the option. Various + values of x are provided to + enable debug messages and additional runtime sanity checks + in different subsystems in the RTS, for + example +RTS -Ds -RTS enables debug + messages from the scheduler. + Use +RTS -? to find out which + debug flags are supported. + + + + Debug messages will be sent to the binary event log file + instead of stdout if the option is + added. This might be useful for reducing the overhead of + debug tracing. + @@ -547,20 +1238,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 + . @@ -619,113 +1303,151 @@ - - “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. + + Getting information about the RTS - 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: + RTS - -char *ghc_rts_opts = "-H128m -K1m"; - + 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") + ,("Host architecture", "x86_64") + ,("Host OS", "linux") + ,("Host vendor", "unknown") + ,("Build platform", "x86_64-unknown-linux") + ,("Build architecture", "x86_64") + ,("Build OS", "linux") + ,("Build vendor", "unknown") + ,("Target platform", "x86_64-unknown-linux") + ,("Target architecture", "x86_64") + ,("Target OS", "linux") + ,("Target vendor", "unknown") + ,("Word size", "64") + ,("Compiler unregisterised", "NO") + ,("Tables next to code", "YES") + ] + + The information is formatted such that it can be read as a + of type [(String, String)]. Currently the following + fields are present: - 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. + + GHC RTS + + Is this program linked against the GHC RTS? (always + "YES"). + + - 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: + + GHC version + + The version of GHC used to compile this program. + + - + + RTS way + + The variant (“way”) of the runtime. The + most common values are rts (vanilla), + rts_thr (threaded runtime, i.e. linked using the + -threaded option) and rts_p + (profiling runtime, i.e. linked using the -prof + option). Other variants include debug + (linked using -debug), + t (ticky-ticky profiling) and + dyn (the RTS is + linked in dynamically, i.e. a shared library, rather than statically + linked into the executable itself). These can be combined, + e.g. you might have rts_thr_debug_p. + + - - void OutOfHeapHook (unsigned long, unsigned long) - OutOfHeapHook + + Target platform, + Target architecture, + Target OS, + Target vendor - - The heap-overflow message. - + + These are the platform the program is compiled to run on. + - - void StackOverflowHook (long int) - StackOverflowHook + + Build platform, + Build architecture, + Build OS, + Build vendor - - The stack-overflow message. - + + These are the platform where the program was built + on. (That is, the target platform of GHC itself.) Ordinarily + this is identical to the target platform. (It could potentially + be different if cross-compiling.) + - - void MallocFailHook (long int) - MallocFailHook + + Host platform, + Host architecture + Host OS + Host vendor - - The message printed if malloc - fails. - + + These are the platform where GHC itself was compiled. + Again, this would normally be identical to the build and + target platforms. + - - 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. - + + Word size + + Either "32" or "64", + reflecting the word size of the target platform. + + - - Getting information about the RTS + + Compiler unregistered + + Was this program compiled with an “unregistered” + version of GHC? (I.e., a version of GHC that has no platform-specific + optimisations compiled in, usually because this is a currently + unsupported platform.) This value will usually be no, unless you're + using an experimental build of GHC. + + - RTS + + Tables next to code + + Putting info tables directly next to entry code is a useful + performance optimisation that is not available on all platforms. + This field tells you whether the program has been compiled with + this optimisation. (Usually yes, except on unusual platforms.) + + + + - 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)].