diff options
Diffstat (limited to 'docs/users_guide/runtime_control.xml')
| -rw-r--r-- | docs/users_guide/runtime_control.xml | 1605 |
1 files changed, 0 insertions, 1605 deletions
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml deleted file mode 100644 index b23f79fabf..0000000000 --- a/docs/users_guide/runtime_control.xml +++ /dev/null @@ -1,1605 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="runtime-control"> - <title>Running a compiled program</title> - - <indexterm><primary>runtime control of Haskell programs</primary></indexterm> - <indexterm><primary>running, compiled program</primary></indexterm> - <indexterm><primary>RTS options</primary></indexterm> - - <para>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, thread scheduling, profiling, and - so on.</para> - - <para> - 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 (<xref linkend="setting-rts-options" />) describes - the various methods, and the following sections describe the RTS - options themselves. - </para> - - <sect2 id="setting-rts-options"> - <title>Setting RTS options</title> - <indexterm><primary>RTS options, setting</primary></indexterm> - - <para> - There are four ways to set RTS options: - - <itemizedlist> - <listitem> - <para> - on the command line between <literal>+RTS ... -RTS</literal>, when running the program - (<xref linkend="rts-opts-cmdline" />) - </para> - </listitem> - <listitem> - <para>at compile-time, using <option>--with-rtsopts</option> - (<xref linkend="rts-opts-compile-time" />) - </para> - </listitem> - <listitem> - <para>with the environment variable <envar>GHCRTS</envar> - (<xref linkend="rts-options-environment" />) - </para> - </listitem> - <listitem> - <para>by overriding “hooks” in the runtime system - (<xref linkend="rts-hooks" />) - </para> - </listitem> - </itemizedlist> - </para> - - <sect3 id="rts-opts-cmdline"> - <title>Setting RTS options on the command line</title> - - <para> - If you set the <literal>-rtsopts</literal> flag appropriately - when linking (see <xref linkend="options-linker" />), you can - give RTS options on the command line when running your - program. - </para> - - <para> - When your Haskell program starts up, the RTS extracts - command-line arguments bracketed between - <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm> - and - <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm> - as its own. For example: - </para> - -<screen> -$ ghc prog.hs -rtsopts -[1 of 1] Compiling Main ( prog.hs, prog.o ) -Linking prog ... -$ ./prog -f +RTS -H32m -S -RTS -h foo bar -</screen> - - <para> - The RTS will - snaffle <option>-H32m</option> <option>-S</option> for itself, - and the remaining arguments <literal>-f -h foo bar</literal> - will be available to your program if/when it calls - <function>System.Environment.getArgs</function>. - </para> - - <para> - No <option>-RTS</option> option is required if the - runtime-system options extend to the end of the command line, as in - this example: - </para> - -<screen> -% hls -ltr /usr/etc +RTS -A5m -</screen> - - <para> - 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 - <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>. - </para> - - <para> - As always, for RTS options that take - <replaceable>size</replaceable>s: If the last character of - <replaceable>size</replaceable> 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 <emphasis>your</emphasis> - fault!) - </para> - - <para> - Giving a <literal>+RTS -?</literal> - <indexterm><primary><option>-?</option></primary><secondary>RTS option</secondary></indexterm> option - will print out the RTS options actually available in your program - (which vary, depending on how you compiled).</para> - - <para> - NOTE: since GHC is itself compiled by GHC, you can change RTS - options in the compiler using the normal - <literal>+RTS ... -RTS</literal> - combination. eg. to set the maximum heap - size for a compilation to 128M, you would add - <literal>+RTS -M128m -RTS</literal> - to the command line. - </para> - </sect3> - - <sect3 id="rts-opts-compile-time"> - <title>Setting RTS options at compile time</title> - - <para> - GHC lets you change the default RTS options for a program at - compile time, using the <literal>-with-rtsopts</literal> - flag (<xref linkend="options-linker" />). 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 <literal>-H128m - -K64m</literal>, link - with <literal>-with-rtsopts="-H128m -K64m"</literal>. - </para> - </sect3> - - <sect3 id="rts-options-environment"> - <title>Setting RTS options with the <envar>GHCRTS</envar> - environment variable</title> - - <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm> - <indexterm><primary>environment variable</primary><secondary>for - setting RTS options</secondary></indexterm> - - <para> - If the <literal>-rtsopts</literal> flag is set to - something other than <literal>none</literal> when linking, - RTS options are also taken from the environment variable - <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary> - </indexterm>. For example, to set the maximum heap size - to 2G for all GHC-compiled programs (using an - <literal>sh</literal>-like shell): - </para> - -<screen> - GHCRTS='-M2G' - export GHCRTS -</screen> - - <para> - RTS options taken from the <envar>GHCRTS</envar> environment - variable can be overridden by options given on the command - line. - </para> - - <para> - Tip: setting something like <literal>GHCRTS=-M2G</literal> - 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). - </para> - </sect3> - - <sect3 id="rts-hooks"> - <title>“Hooks” to change RTS behaviour</title> - - <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm> - <indexterm><primary>RTS hooks</primary></indexterm> - <indexterm><primary>RTS behaviour, changing</primary></indexterm> - - <para>GHC lets you exercise rudimentary control over certain 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 these hooks, but by writing your - own version and linking it on the GHC command line, you can - override the defaults.</para> - - <para>Owing to the vagaries of DLL linking, these hooks don't work - under Windows when the program is built dynamically.</para> - - <para>You can change the messages printed when the runtime - system “blows up,” e.g., on stack overflow. The hooks - for these are as follows:</para> - - <variablelist> - - <varlistentry> - <term> - <function>void OutOfHeapHook (unsigned long, unsigned long)</function> - <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm> - </term> - <listitem> - <para>The heap-overflow message.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <function>void StackOverflowHook (long int)</function> - <indexterm><primary><function>StackOverflowHook</function></primary></indexterm> - </term> - <listitem> - <para>The stack-overflow message.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <function>void MallocFailHook (long int)</function> - <indexterm><primary><function>MallocFailHook</function></primary></indexterm> - </term> - <listitem> - <para>The message printed if <function>malloc</function> - fails.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - </sect2> - - <sect2 id="rts-options-misc"> - <title>Miscellaneous RTS options</title> - - <variablelist> - <varlistentry> - <term><option>-V<replaceable>secs</replaceable></option> - <indexterm><primary><option>-V</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para>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 (<xref - linkend="using-concurrent" />) and the heap profiling - timer <xref linkend="rts-options-heap-prof" />. Also, the - time profiler uses the RTS timer signal directly to record - time profiling samples.</para> - - <para>Normally, setting the <option>-V</option> option - directly is not necessary: the resolution of the RTS timer is - adjusted automatically if a short interval is requested with - the <option>-C</option> or <option>-i</option> options. - However, setting <option>-V</option> is required in order to - increase the resolution of the time profiler.</para> - - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--install-signal-handlers=<replaceable>yes|no</replaceable></option> - <indexterm><primary><option>--install-signal-handlers</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para>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.</para> - - <para>Note that even - with <option>--install-signal-handlers=no</option>, 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 <literal>-V0</literal> RTS option (see - above). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-xm<replaceable>address</replaceable></option> - <indexterm><primary><option>-xm</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para> - WARNING: this option is for working around memory - allocation problems only. Do not use unless GHCi fails - with a message like “<literal>failed to mmap() memory below 2Gb</literal>”. If you need to use this option to get GHCi working - on your machine, please file a bug. - </para> - - <para> - 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, <literal>+RTS -xm20000000 - -RTS</literal> 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. <literal>mmap</literal> - with <literal>MAP_32BIT</literal> on Linux), or - otherwise <literal>-xm40000000</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-xq<replaceable>size</replaceable></option> - <indexterm><primary><option>-xq</option></primary><secondary>RTS - option</secondary></indexterm></term> - <listitem> - <para> - [Default: 100k] This option relates to allocation - limits; for more about this see <ulink - url="&libraryBaseLocation;/GHC-Conc.html#v%3AenableAllocationLimit"><literal>enableAllocationLimit</literal></ulink>. - When a thread hits its allocation limit, the RTS throws an - exception to the thread, and the thread gets an additional - quota of allocation before the exception is raised again, - the idea being so that the thread can execute its exception - handlers. The <option>-xq</option> controls the size of - this additional quota. - </para> - </listitem> - </varlistentry> - - </variablelist> - </sect2> - - <sect2 id="rts-options-gc"> - <title>RTS options to control the garbage collector</title> - - <indexterm><primary>garbage collector</primary><secondary>options</secondary></indexterm> - <indexterm><primary>RTS options</primary><secondary>garbage collection</secondary></indexterm> - - <para>There are several options to give you precise control over - garbage collection. Hopefully, you won't need any of these in - normal operation, but there are several things that can be tweaked - for maximum performance.</para> - - <variablelist> - - <varlistentry> - <term> - <option>-A</option><replaceable>size</replaceable> - <indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>allocation area, size</primary></indexterm> - </term> - <listitem> - <para>[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 <option>-H</option>, below).</para> - - <para>Increasing the allocation area size may or may not - give better performance (a bigger allocation area means - worse cache behaviour but fewer garbage collections and less - promotion).</para> - - <para>With only 1 generation (<option>-G1</option>) the - <option>-A</option> option specifies the minimum allocation - area, since the actual size of the allocation area will be - resized according to the amount of data in the heap (see - <option>-F</option>, below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O</option><replaceable>size</replaceable> - <indexterm><primary><option>-O</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>old generation, size</primary></indexterm> - </term> - <listitem> - <para>[Default: 1m] Set the minimum size of the - old generation. The old generation is collected whenever it - grows to this size or the value of the <option>-F</option> option - multiplied by the size of the live data at the previous major - collection, whichever is larger.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-n</option><replaceable>size</replaceable> - <indexterm><primary><option>-n</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>allocation area, chunk size</primary></indexterm> - </term> - <listitem> - <para>[Default: 0, Example: - <literal>-n4m</literal>] When set to a non-zero value, - this option divides the allocation area (<option>-A</option> - value) into chunks of the specified size. During execution, - when a processor exhausts its current chunk, it is given - another chunk from the pool until the pool is exhausted, at - which point a collection is triggered.</para> - - <para>This option is only useful when running in parallel - (<option>-N2</option> or greater). It allows the processor - cores to make better use of the available allocation area, - even when cores are allocating at different rates. Without - <option>-n</option>, each core gets a fixed-size allocation - area specified by the <option>-A</option>, and the first - core to exhaust its allocation area triggers a GC across all - the cores. This can result in a collection happening when - the allocation areas of some cores are only partially full, - so the purpose of the <option>-n</option> is to allow cores - that are allocating faster to get more of the allocation - area. This means less frequent GC, leading a lower GC - overhead for the same heap size.</para> - - <para>This is particularly useful in conjunction with larger - <option>-A</option> values, for example <option>-A64m - -n4m</option> is a useful combination on larger core counts - (8+).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-c</option> - <indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>garbage collection</primary><secondary>compacting</secondary></indexterm> - <indexterm><primary>compacting garbage collection</primary></indexterm> - </term> - <listitem> - <para>Use a compacting algorithm for collecting the oldest - generation. By default, the oldest generation is collected - using a copying algorithm; this option causes it to be - compacted in-place instead. The compaction algorithm is - slower than the copying algorithm, but the savings in memory - use can be considerable.</para> - - <para>For a given heap size (using the <option>-H</option> - option), compaction can in fact reduce the GC cost by - allowing fewer GCs to be performed. This is more likely - when the ratio of live data to heap size is high, say - >30%.</para> - - <para>NOTE: compaction doesn't currently work when a single - generation is requested using the <option>-G1</option> - option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option><replaceable>n</replaceable></term> - - <listitem> - <para>[Default: 30] Automatically enable - compacting collection when the live data exceeds - <replaceable>n</replaceable>% of the maximum heap size - (see the <option>-M</option> option). Note that the maximum - heap size is unlimited by default, so this option has no - effect unless the maximum heap size is set with - <option>-M</option><replaceable>size</replaceable>. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-F</option><replaceable>factor</replaceable> - <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap size, factor</primary></indexterm> - </term> - <listitem> - - <para>[Default: 2] This option controls the amount - of memory reserved for the older generations (and in the - case of a two space collector the size of the allocation - area) as a factor of the amount of live data. For example, - if there was 2M of live data in the oldest generation when - we last collected it, then by default we'll wait until it - grows to 4M before collecting it again.</para> - - <para>The default seems to work well here. If you have - plenty of memory, it is usually better to use - <option>-H</option><replaceable>size</replaceable> than to - increase - <option>-F</option><replaceable>factor</replaceable>.</para> - - <para>The <option>-F</option> setting will be automatically - reduced by the garbage collector when the maximum heap size - (the <option>-M</option><replaceable>size</replaceable> - setting) is approaching.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-G</option><replaceable>generations</replaceable> - <indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>generations, number of</primary></indexterm> - </term> - <listitem> - <para>[Default: 2] Set the number of generations - used by the garbage collector. The default of 2 seems to be - good, but the garbage collector can support any number of - generations. Anything larger than about 4 is probably not a - good idea unless your program runs for a - <emphasis>long</emphasis> time, because the oldest - generation will hardly ever get collected.</para> - - <para>Specifying 1 generation with <option>+RTS -G1</option> - gives you a simple 2-space collector, as you would expect. - In a 2-space collector, the <option>-A</option> option (see - above) specifies the <emphasis>minimum</emphasis> allocation - area size, since the allocation area will grow with the - amount of live data in the heap. In a multi-generational - collector the allocation area is a fixed size (unless you - use the <option>-H</option> option, see below).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-qg<optional><replaceable>gen</replaceable></optional></option> - <indexterm><primary><option>-qg</option><secondary>RTS - option</secondary></primary></indexterm> - </term> - <listitem> - <para>[New in GHC 6.12.1] [Default: 0] - Use parallel GC in - generation <replaceable>gen</replaceable> and higher. - Omitting <replaceable>gen</replaceable> turns off the - parallel GC completely, reverting to sequential GC.</para> - - <para>The default parallel GC settings are usually suitable - for parallel programs (i.e. those - using <literal>par</literal>, 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 <literal>-N</literal> - option, and additionally it might be beneficial to - restrict parallel GC to the old generation - with <literal>-qg1</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-qb<optional><replaceable>gen</replaceable></optional></option> - <indexterm><primary><option>-qb</option><secondary>RTS - option</secondary></primary></indexterm> - </term> - <listitem> - <para> - [New in GHC 6.12.1] [Default: 1] Use - load-balancing in the parallel GC in - generation <replaceable>gen</replaceable> and higher. - Omitting <replaceable>gen</replaceable> disables - load-balancing entirely.</para> - - <para> - 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 <literal>-qb</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-H</option><optional><replaceable>size</replaceable></optional> - <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap size, suggested</primary></indexterm> - </term> - <listitem> - <para>[Default: 0] This option provides a - “suggested heap size” for the garbage - collector. Think - of <option>-H<replaceable>size</replaceable></option> as a - variable <option>-A</option> option. It says: I want to - use at least <replaceable>size</replaceable> bytes, so use - whatever is left over to increase the <option>-A</option> - value.</para> - - <para>This option does not put - a <emphasis>limit</emphasis> on the heap size: the heap - may grow beyond the given size as usual.</para> - - <para>If <replaceable>size</replaceable> is omitted, then - the garbage collector will take the size of the heap at - the previous GC as the <replaceable>size</replaceable>. - This has the effect of allowing for a - larger <option>-A</option> value but without increasing - the overall memory requirements of the program. It can be - useful when the default small <option>-A</option> value is - suboptimal, as it can be in programs that create large - amounts of long-lived data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-I</option><replaceable>seconds</replaceable> - <indexterm><primary><option>-I</option></primary> - <secondary>RTS option</secondary> - </indexterm> - <indexterm><primary>idle GC</primary> - </indexterm> - </term> - <listitem> - <para>(default: 0.3) In the threaded and SMP versions of the RTS (see - <option>-threaded</option>, <xref linkend="options-linker" />), a - major GC is automatically performed if the runtime has been idle - (no Haskell computation has been running) for a period of time. - The amount of idle time which must pass before a GC is performed is - set by the <option>-I</option><replaceable>seconds</replaceable> - option. Specifying <option>-I0</option> disables the idle GC.</para> - - <para>For an interactive application, it is probably a good idea to - use the idle GC, because this will allow finalizers to run and - deadlocked threads to be detected in the idle time when no Haskell - computation is happening. Also, it will mean that a GC is less - likely to happen when the application is busy, and so - responsiveness may be improved. However, if the amount of live data in - the heap is particularly large, then the idle GC can cause a - significant delay, and too small an interval could adversely affect - interactive responsiveness.</para> - - <para>This is an experimental feature, please let us know if it - causes problems and/or could benefit from further tuning.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ki</option><replaceable>size</replaceable> - <indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>stack, initial size</primary></indexterm> - </term> - <listitem> - <para> - [Default: 1k] Set the initial stack size for new - threads. (Note: this flag used to be - simply <option>-k</option>, but was renamed - to <option>-ki</option> in GHC 7.2.1. The old name is - still accepted for backwards compatibility, but that may - be removed in a future version). - </para> - - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-kc</option><replaceable>size</replaceable> - <indexterm><primary><option>-kc</option></primary><secondary>RTS - option</secondary></indexterm> - <indexterm><primary>stack</primary><secondary>chunk size</secondary></indexterm> - </term> - <listitem> - <para> - [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 <option>-K</option> is - reached. - </para> - - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-kb</option><replaceable>size</replaceable> - <indexterm><primary><option>-kc</option></primary><secondary>RTS - option</secondary></indexterm> - <indexterm><primary>stack</primary><secondary>chunk buffer size</secondary></indexterm> - </term> - <listitem> - <para> - [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>-kb</option> - option. - </para> - <para> - Note that to avoid wasting space, this value should - typically be less than 10% of the size of a stack - chunk (<option>-kc</option>), because in a chain of stack - chunks, each chunk will have a gap of unused space of this - size. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-K</option><replaceable>size</replaceable> - <indexterm><primary><option>-K</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>stack, maximum size</primary></indexterm> - </term> - <listitem> - <para>[Default: 80% physical memory size] Set the - maximum stack size for an individual thread to - <replaceable>size</replaceable> bytes. If the thread - attempts to exceed this limit, it will be sent the - <literal>StackOverflow</literal> exception. The - limit can be disabled entirely by specifying a size of zero. - </para> - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-m</option><replaceable>n</replaceable> - <indexterm><primary><option>-m</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap, minimum free</primary></indexterm> - </term> - <listitem> - <para>Minimum % <replaceable>n</replaceable> of heap - which must be available for allocation. The default is - 3%.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-M</option><replaceable>size</replaceable> - <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>heap size, maximum</primary></indexterm> - </term> - <listitem> - <para>[Default: unlimited] Set the maximum heap size to - <replaceable>size</replaceable> bytes. The heap normally - grows and shrinks according to the memory requirements of - the program. The only reason for having this option is to - stop the heap growing without bound and filling up all the - available swap space, which at the least will result in the - program being summarily killed by the operating - system.</para> - - <para>The maximum heap size also affects other garbage - collection parameters: when the amount of live data in the - heap exceeds a certain fraction of the maximum heap size, - compacting collection will be automatically enabled for the - oldest generation, and the <option>-F</option> parameter - will be reduced in order to avoid exceeding the maximum heap - size.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-T</option> - <indexterm><primary><option>-T</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>-t</option><optional><replaceable>file</replaceable></optional> - <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>-s</option><optional><replaceable>file</replaceable></optional> - <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>-S</option><optional><replaceable>file</replaceable></optional> - <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <term> - <option>--machine-readable</option> - <indexterm><primary><option>--machine-readable</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>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: - <option>-T</option> collects the data but produces no output - <option>-t</option> produces a single line of output in the - same format as GHC's <option>-Rghc-timing</option> option, - <option>-s</option> produces a more detailed summary at the - end of the program, and <option>-S</option> additionally - produces information about each and every garbage - collection.</para> - - <para>The output is placed in - <replaceable>file</replaceable>. If - <replaceable>file</replaceable> is omitted, then the output - is sent to <constant>stderr</constant>.</para> - - <para> - If you use the <literal>-T</literal> flag then, you should - access the statistics using - <ulink url="&libraryBaseLocation;/GHC-Stats.html">GHC.Stats</ulink>. - </para> - - <para> - If you use the <literal>-t</literal> flag then, when your - program finishes, you will see something like this: - </para> - -<programlisting> -<<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>> -</programlisting> - - <para> - This tells you: - </para> - - <itemizedlist> - <listitem> - <para> - The total number of bytes allocated by the program over the - whole run. - </para> - </listitem> - <listitem> - <para> - The total number of garbage collections performed. - </para> - </listitem> - <listitem> - <para> - 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 <option>-hT</option> RTS option - (<xref linkend="rts-profiling" />). - </para> - </listitem> - <listitem> - <para> - The peak memory the RTS has allocated from the OS. - </para> - </listitem> - <listitem> - <para> - 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). - </para> - </listitem> - </itemizedlist> - - <para> - You can also get this in a more future-proof, machine readable - format, with <literal>-t --machine-readable</literal>: - </para> - -<programlisting> - [("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") - ] -</programlisting> - - <para> - If you use the <literal>-s</literal> 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): - </para> - -<programlisting> - 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 -</programlisting> - - <itemizedlist> - <listitem> - <para> - The "bytes allocated in the heap" is the total bytes allocated - by the program over the whole run. - </para> - </listitem> - <listitem> - <para> - GHC uses a copying garbage collector by default. "bytes copied - during GC" tells you how many bytes it had to copy during - garbage collection. - </para> - </listitem> - <listitem> - <para> - 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. - </para> - </listitem> - <listitem> - <para> - 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. - </para> - </listitem> - <listitem> - <para> - The "total memory in use" tells you the peak memory the RTS has - allocated from the OS. - </para> - </listitem> - <listitem> - <para> - 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. - </para> - </listitem> - <listitem> - <para>The <literal>SPARKS</literal> statistic refers to the - use of <literal>Control.Parallel.par</literal> and related - functionality in the program. Each spark represents a call - to <literal>par</literal>; 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.</para> - </listitem> - <listitem> - <para> - 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. - </para> - <para> - %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). - </para> - </listitem> - </itemizedlist> - - <para> - The <literal>-S</literal> flag, as well as giving the same - output as the <literal>-s</literal> flag, prints information - about each GC as it happens: - </para> - -<programlisting> - 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) -</programlisting> - - <para> - For each garbage collection, we print: - </para> - - <itemizedlist> - <listitem> - <para> - How many bytes we allocated this garbage collection. - </para> - </listitem> - <listitem> - <para> - How many bytes we copied this garbage collection. - </para> - </listitem> - <listitem> - <para> - How many bytes are currently live. - </para> - </listitem> - <listitem> - <para> - How long this garbage collection took (CPU time and elapsed - wall clock time). - </para> - </listitem> - <listitem> - <para> - How long the program has been running (CPU time and elapsed - wall clock time). - </para> - </listitem> - <listitem> - <para> - How many page faults occurred this garbage collection. - </para> - </listitem> - <listitem> - <para> - How many page faults occurred since the end of the last garbage - collection. - </para> - </listitem> - <listitem> - <para> - Which generation is being garbage collected. - </para> - </listitem> - </itemizedlist> - - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2> - <title>RTS options for concurrency and parallelism</title> - - <para>The RTS options related to concurrency are described in - <xref linkend="using-concurrent" />, and those for parallelism in - <xref linkend="parallel-options"/>.</para> - </sect2> - - <sect2 id="rts-profiling"> - <title>RTS options for profiling</title> - - <para>Most profiling runtime options are only available when you - compile your program for profiling (see - <xref linkend="prof-compiler-options" />, and - <xref linkend="rts-options-heap-prof" /> for the runtime options). - However, there is one profiling option that is available - for ordinary non-profiled executables:</para> - - <variablelist> - <varlistentry> - <term> - <option>-hT</option> - <indexterm><primary><option>-hT</option></primary><secondary>RTS - option</secondary></indexterm> - </term> - <listitem> - <para>(can be shortened to <option>-h</option>.) Generates a basic heap profile, in the - file <literal><replaceable>prog</replaceable>.hp</literal>. - To produce the heap profile graph, - use <command>hp2ps</command> (see <xref linkend="hp2ps" - />). The basic heap profile is broken down by data - constructor, with other types of closures (functions, thunks, - etc.) grouped into broad categories - (e.g. <literal>FUN</literal>, <literal>THUNK</literal>). To - get a more detailed profile, use the full profiling - support (<xref linkend="profiling" />).</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="rts-eventlog"> - <title>Tracing</title> - - <indexterm><primary>tracing</primary></indexterm> - <indexterm><primary>events</primary></indexterm> - <indexterm><primary>eventlog files</primary></indexterm> - - <para> - When the program is linked with the <option>-eventlog</option> - option (<xref linkend="options-linker" />), runtime events can - be logged in two ways: - </para> - - <itemizedlist> - <listitem> - <para> - In binary format to a file for later analysis by a - variety of tools. One such tool - is <ulink url="http://www.haskell.org/haskellwiki/ThreadScope">ThreadScope</ulink><indexterm><primary>ThreadScope</primary></indexterm>, - which interprets the event log to produce a visual parallel - execution profile of the program. - </para> - </listitem> - <listitem> - <para> - As text to standard output, for debugging purposes. - </para> - </listitem> - </itemizedlist> - - <variablelist> - <varlistentry> - <term> - <option>-l<optional><replaceable>flags</replaceable></optional></option> - <indexterm><primary><option>-l</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - Log events in binary format to the - file <filename><replaceable>program</replaceable>.eventlog</filename>. - Without any <replaceable>flags</replaceable> specified, this logs a - default set of events, suitable for use with tools like ThreadScope. - </para> - - <para> - For some special use cases you may want more control over which - events are included. The <replaceable>flags</replaceable> is a - sequence of zero or more characters indicating which classes of - events to log. Currently these the classes of events that can - be enabled/disabled: - <simplelist> - <member> - <option>s</option> — scheduler events, including Haskell - thread creation and start/stop events. Enabled by default. - </member> - <member> - <option>g</option> — GC events, including GC start/stop. - Enabled by default. - </member> - <member> - <option>p</option> — parallel sparks (sampled). - Enabled by default. - </member> - <member> - <option>f</option> — parallel sparks (fully accurate). - Disabled by default. - </member> - <member> - <option>u</option> — user events. These are events emitted - from Haskell code using functions such as - <literal>Debug.Trace.traceEvent</literal>. Enabled by default. - </member> - </simplelist> - </para> - - <para> - You can disable specific classes, or enable/disable all classes at - once: - <simplelist> - <member> - <option>a</option> — enable all event classes listed above - </member> - <member> - <option>-<replaceable>x</replaceable></option> — disable the - given class of events, for any event class listed above or - <option>-a</option> for all classes - </member> - </simplelist> - For example, <option>-l-ag</option> would disable all event classes - (<option>-a</option>) except for GC events (<option>g</option>). - </para> - - <para> - For spark events there are two modes: sampled and fully accurate. - There are various events in the life cycle of each spark, usually - just creating and running, but there are some more exceptional - possibilities. In the sampled mode the number of occurrences of each - kind of spark event is sampled at frequent intervals. In the fully - accurate mode every spark event is logged individually. The latter - has a higher runtime overhead and is not enabled by default. - </para> - - <para> - The format of the log file is described by the header - <filename>EventLogFormat.h</filename> that comes with - GHC, and it can be parsed in Haskell using - the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink> - library. To dump the contents of - a <literal>.eventlog</literal> file as text, use the - tool <literal>ghc-events show</literal> that comes with - the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink> - package. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-v</option><optional><replaceable>flags</replaceable></optional> - <indexterm><primary><option>-v</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - Log events as text to standard output, instead of to - the <literal>.eventlog</literal> file. - The <replaceable>flags</replaceable> are the same as - for <option>-l</option>, with the additional - option <literal>t</literal> which indicates that the - each event printed should be preceded by a timestamp value - (in the binary <literal>.eventlog</literal> file, all - events are automatically associated with a timestamp). - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - The debugging - options <option>-D<replaceable>x</replaceable></option> also - generate events which are logged using the tracing framework. - By default those events are dumped as text to stdout - (<option>-D<replaceable>x</replaceable></option> - implies <option>-v</option>), but they may instead be stored in - the binary eventlog file by using the <option>-l</option> - option. - </para> - </sect2> - - <sect2 id="rts-options-debugging"> - <title>RTS options for hackers, debuggers, and over-interested - souls</title> - - <indexterm><primary>RTS options, hacking/debugging</primary></indexterm> - - <para>These RTS options might be used (a) to avoid a GHC bug, - (b) to see “what's really happening”, or - (c) because you feel like it. Not recommended for everyday - use!</para> - - <variablelist> - - <varlistentry> - <term> - <option>-B</option> - <indexterm><primary><option>-B</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Sound the bell at the start of each (major) garbage - collection.</para> - - <para>Oddly enough, people really do use this option! Our - pal in Durham (England), Paul Callaghan, writes: “Some - people here use it for a variety of - purposes—honestly!—e.g., confirmation that the - code/machine is doing something, infinite loop detection, - gauging cost of recently added code. Certain people can even - tell what stage [the program] is in by the beep - pattern. But the major use is for annoying others in the - same office…”</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-D</option><replaceable>x</replaceable> - <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para> - An RTS debugging flag; only available if the program was - linked with the <option>-debug</option> option. Various - values of <replaceable>x</replaceable> are provided to - enable debug messages and additional runtime sanity checks - in different subsystems in the RTS, for - example <literal>+RTS -Ds -RTS</literal> enables debug - messages from the scheduler. - Use <literal>+RTS -?</literal> to find out which - debug flags are supported. - </para> - - <para> - Debug messages will be sent to the binary event log file - instead of stdout if the <option>-l</option> option is - added. This might be useful for reducing the overhead of - debug tracing. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-r</option><replaceable>file</replaceable> - <indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm> - <indexterm><primary>ticky ticky profiling</primary></indexterm> - <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm> - </term> - <listitem> - <para>Produce “ticky-ticky” statistics at the - end of the program run (only available if the program was - linked with <option>-debug</option>). - The <replaceable>file</replaceable> business works just like - on the <option>-S</option> RTS option, above.</para> - - <para>For more information on ticky-ticky profiling, see - <xref linkend="ticky-ticky"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-xc</option> - <indexterm><primary><option>-xc</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>(Only available when the program is compiled for - profiling.) When an exception is raised in the program, - this option causes a stack trace to be - dumped to <literal>stderr</literal>.</para> - - <para>This can be particularly useful for debugging: if your - program is complaining about a <literal>head []</literal> - error and you haven't got a clue which bit of code is - causing it, compiling with <literal>-prof - -fprof-auto</literal> and running with <literal>+RTS -xc - -RTS</literal> will tell you exactly the call stack at the - point the error was raised.</para> - - <para>The output contains one report for each exception - raised in the program (the program might raise and catch - several exceptions during its execution), where each report - looks something like this: - </para> - -<screen> -*** Exception raised (reporting due to +RTS -xc), stack trace: - GHC.List.CAF - --> evaluated by: Main.polynomial.table_search, - called from Main.polynomial.theta_index, - called from Main.polynomial, - called from Main.zonal_pressure, - called from Main.make_pressure.p, - called from Main.make_pressure, - called from Main.compute_initial_state.p, - called from Main.compute_initial_state, - called from Main.CAF - ... -</screen> - <para>The stack trace may often begin with something - uninformative like <literal>GHC.List.CAF</literal>; this is - an artifact of GHC's optimiser, which lifts out exceptions - to the top-level where the profiling system assigns them to - the cost centre "CAF". However, <literal>+RTS -xc</literal> - doesn't just print the current stack, it looks deeper and - reports the stack at the time the CAF was evaluated, and it - may report further stacks until a non-CAF stack is found. In - the example above, the next stack (after <literal>--> - evaluated by</literal>) contains plenty of information about - what the program was doing when it evaluated <literal>head - []</literal>.</para> - - <para>Implementation details aside, the function names in - the stack should hopefully give you enough clues to track - down the bug.</para> - - <para> - See also the function <literal>traceStack</literal> in the - module <literal>Debug.Trace</literal> for another way to - view call stacks. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-Z</option> - <indexterm><primary><option>-Z</option></primary><secondary>RTS option</secondary></indexterm> - </term> - <listitem> - <para>Turn <emphasis>off</emphasis> “update-frame - squeezing” at garbage-collection time. (There's no - particularly good reason to turn it off, except to ensure - the accuracy of certain data collected regarding thunk entry - counts.)</para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2 id="ghc-info"> - <title>Getting information about the RTS</title> - - <indexterm><primary>RTS</primary></indexterm> - - <para>It is possible to ask the RTS to give some information about - itself. To do this, use the <option>--info</option> flag, e.g.</para> -<screen> -$ ./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") - ] -</screen> - <para>The information is formatted such that it can be read as a - of type <literal>[(String, String)]</literal>. Currently the following - fields are present:</para> - - <variablelist> - - <varlistentry> - <term><literal>GHC RTS</literal></term> - <listitem> - <para>Is this program linked against the GHC RTS? (always - "YES").</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>GHC version</literal></term> - <listitem> - <para>The version of GHC used to compile this program.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>RTS way</literal></term> - <listitem> - <para>The variant (“way”) of the runtime. The - most common values are <literal>rts_v</literal> (vanilla), - <literal>rts_thr</literal> (threaded runtime, i.e. linked using the - <literal>-threaded</literal> option) and <literal>rts_p</literal> - (profiling runtime, i.e. linked using the <literal>-prof</literal> - option). Other variants include <literal>debug</literal> - (linked using <literal>-debug</literal>), and - <literal>dyn</literal> (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 <literal>rts_thr_debug_p</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>Target platform</literal>, - <literal>Target architecture</literal>, - <literal>Target OS</literal>, - <literal>Target vendor</literal> - </term> - <listitem> - <para>These are the platform the program is compiled to run on.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>Build platform</literal>, - <literal>Build architecture</literal>, - <literal>Build OS</literal>, - <literal>Build vendor</literal> - </term> - <listitem> - <para>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.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>Host platform</literal>, - <literal>Host architecture</literal> - <literal>Host OS</literal> - <literal>Host vendor</literal> - </term> - <listitem> - <para>These are the platform where GHC itself was compiled. - Again, this would normally be identical to the build and - target platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Word size</literal></term> - <listitem> - <para>Either <literal>"32"</literal> or <literal>"64"</literal>, - reflecting the word size of the target platform.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Compiler unregistered</literal></term> - <listitem> - <para>Was this program compiled with an - <link linkend="unreg">“unregistered”</link> - 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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Tables next to code</literal></term> - <listitem> - <para>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.)</para> - </listitem> - </varlistentry> - - </variablelist> - - </sect2> -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> |