1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <sect1 id="runtime-control">
3 <title>Running a compiled program</title>
5 <indexterm><primary>runtime control of Haskell programs</primary></indexterm>
6 <indexterm><primary>running, compiled program</primary></indexterm>
7 <indexterm><primary>RTS options</primary></indexterm>
9 <para>To make an executable program, the GHC system compiles your
10 code and then links it with a non-trivial runtime system (RTS),
11 which handles storage management, profiling, etc.</para>
13 <para>You have some control over the behaviour of the RTS, by giving
14 special command-line arguments to your program.</para>
16 <para>When your Haskell program starts up, its RTS extracts
17 command-line arguments bracketed between
18 <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm>
20 <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm>
21 as its own. For example:</para>
24 % ./a.out -f +RTS -p -S -RTS -h foo bar
27 <para>The RTS will snaffle <option>-p</option> <option>-S</option>
28 for itself, and the remaining arguments <literal>-f -h foo bar</literal>
29 will be handed to your program if/when it calls
30 <function>System.getArgs</function>.</para>
32 <para>No <option>-RTS</option> option is required if the
33 runtime-system options extend to the end of the command line, as in
37 % hls -ltr /usr/etc +RTS -A5m
40 <para>If you absolutely positively want all the rest of the options
41 in a command line to go to the program (and not the RTS), use a
42 <option>––RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.</para>
44 <para>As always, for RTS options that take
45 <replaceable>size</replaceable>s: If the last character of
46 <replaceable>size</replaceable> is a K or k, multiply by 1000; if an
47 M or m, by 1,000,000; if a G or G, by 1,000,000,000. (And any
48 wraparound in the counters is <emphasis>your</emphasis>
51 <para>Giving a <literal>+RTS -f</literal>
52 <indexterm><primary><option>-f</option></primary><secondary>RTS option</secondary></indexterm> option
53 will print out the RTS options actually available in your program
54 (which vary, depending on how you compiled).</para>
56 <para>NOTE: since GHC is itself compiled by GHC, you can change RTS
57 options in the compiler using the normal
58 <literal>+RTS ... -RTS</literal>
59 combination. eg. to increase the maximum heap
60 size for a compilation to 128M, you would add
61 <literal>+RTS -M128m -RTS</literal>
62 to the command line.</para>
64 <sect2 id="rts-optinos-environment">
65 <title>Setting global RTS options</title>
67 <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm>
68 <indexterm><primary>environment variable</primary><secondary>for
69 setting RTS options</secondary></indexterm>
71 <para>RTS options are also taken from the environment variable
72 <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary>
73 </indexterm>. For example, to set the maximum heap size
74 to 128M for all GHC-compiled programs (using an
75 <literal>sh</literal>-like shell):</para>
82 <para>RTS options taken from the <envar>GHCRTS</envar> environment
83 variable can be overridden by options given on the command
88 <sect2 id="rts-options-misc">
89 <title>Miscellaneous RTS options</title>
93 <term><option>-V<replaceable>secs</replaceable></option>
94 <indexterm><primary><option>-V</option></primary><secondary>RTS
95 option</secondary></indexterm></term>
97 <para>Sets the interval that the RTS clock ticks at. The
98 runtime uses a single timer signal to count ticks; this timer
99 signal is used to control the context switch timer (<xref
100 linkend="sec-using-concurrent" />) and the heap profiling
101 timer <xref linkend="rts-options-heap-prof" />. Also, the
102 time profiler uses the RTS timer signal directly to record
103 time profiling samples.</para>
105 <para>Normally, setting the <option>-V</option> option
106 directly is not necessary: the resolution of the RTS timer is
107 adjusted automatically if a short interval is requested with
108 the <option>-C</option> or <option>-i</option> options.
109 However, setting <option>-V</option> is required in order to
110 increase the resolution of the time profiler.</para>
116 <sect2 id="rts-options-gc">
117 <title>RTS options to control the garbage collector</title>
119 <indexterm><primary>garbage collector</primary><secondary>options</secondary></indexterm>
120 <indexterm><primary>RTS options</primary><secondary>garbage collection</secondary></indexterm>
122 <para>There are several options to give you precise control over
123 garbage collection. Hopefully, you won't need any of these in
124 normal operation, but there are several things that can be tweaked
125 for maximum performance.</para>
131 <option>-A</option><replaceable>size</replaceable>
132 <indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm>
133 <indexterm><primary>allocation area, size</primary></indexterm>
136 <para>[Default: 256k] Set the allocation area size
137 used by the garbage collector. The allocation area
138 (actually generation 0 step 0) is fixed and is never resized
139 (unless you use <option>-H</option>, below).</para>
141 <para>Increasing the allocation area size may or may not
142 give better performance (a bigger allocation area means
143 worse cache behaviour but fewer garbage collections and less
146 <para>With only 1 generation (<option>-G1</option>) the
147 <option>-A</option> option specifies the minimum allocation
148 area, since the actual size of the allocation area will be
149 resized according to the amount of data in the heap (see
150 <option>-F</option>, below).</para>
157 <indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary></indexterm>
158 <indexterm><primary>garbage collection</primary><secondary>compacting</secondary></indexterm>
159 <indexterm><primary>compacting garbage collection</primary></indexterm>
162 <para>Use a compacting algorithm for collecting the oldest
163 generation. By default, the oldest generation is collected
164 using a copying algorithm; this option causes it to be
165 compacted in-place instead. The compaction algorithm is
166 slower than the copying algorithm, but the savings in memory
167 use can be considerable.</para>
169 <para>For a given heap size (using the <option>-H</option>
170 option), compaction can in fact reduce the GC cost by
171 allowing fewer GCs to be performed. This is more likely
172 when the ratio of live data to heap size is high, say
173 >30%.</para>
175 <para>NOTE: compaction doesn't currently work when a single
176 generation is requested using the <option>-G1</option>
182 <term><option>-c</option><replaceable>n</replaceable></term>
185 <para>[Default: 30] Automatically enable
186 compacting collection when the live data exceeds
187 <replaceable>n</replaceable>% of the maximum heap size
188 (see the <option>-M</option> option). Note that the maximum
189 heap size is unlimited by default, so this option has no
190 effect unless the maximum heap size is set with
191 <option>-M</option><replaceable>size</replaceable>. </para>
197 <option>-F</option><replaceable>factor</replaceable>
198 <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>
199 <indexterm><primary>heap size, factor</primary></indexterm>
203 <para>[Default: 2] This option controls the amount
204 of memory reserved for the older generations (and in the
205 case of a two space collector the size of the allocation
206 area) as a factor of the amount of live data. For example,
207 if there was 2M of live data in the oldest generation when
208 we last collected it, then by default we'll wait until it
209 grows to 4M before collecting it again.</para>
211 <para>The default seems to work well here. If you have
212 plenty of memory, it is usually better to use
213 <option>-H</option><replaceable>size</replaceable> than to
215 <option>-F</option><replaceable>factor</replaceable>.</para>
217 <para>The <option>-F</option> setting will be automatically
218 reduced by the garbage collector when the maximum heap size
219 (the <option>-M</option><replaceable>size</replaceable>
220 setting) is approaching.</para>
226 <option>-G</option><replaceable>generations</replaceable>
227 <indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm>
228 <indexterm><primary>generations, number of</primary></indexterm>
231 <para>[Default: 2] Set the number of generations
232 used by the garbage collector. The default of 2 seems to be
233 good, but the garbage collector can support any number of
234 generations. Anything larger than about 4 is probably not a
235 good idea unless your program runs for a
236 <emphasis>long</emphasis> time, because the oldest
237 generation will hardly ever get collected.</para>
239 <para>Specifying 1 generation with <option>+RTS -G1</option>
240 gives you a simple 2-space collector, as you would expect.
241 In a 2-space collector, the <option>-A</option> option (see
242 above) specifies the <emphasis>minimum</emphasis> allocation
243 area size, since the allocation area will grow with the
244 amount of live data in the heap. In a multi-generational
245 collector the allocation area is a fixed size (unless you
246 use the <option>-H</option> option, see below).</para>
252 <option>-H</option><replaceable>size</replaceable>
253 <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
254 <indexterm><primary>heap size, suggested</primary></indexterm>
257 <para>[Default: 0] This option provides a
258 “suggested heap size” for the garbage collector. The
259 garbage collector will use about this much memory until the
260 program residency grows and the heap size needs to be
261 expanded to retain reasonable performance.</para>
263 <para>By default, the heap will start small, and grow and
264 shrink as necessary. This can be bad for performance, so if
265 you have plenty of memory it's worthwhile supplying a big
266 <option>-H</option><replaceable>size</replaceable>. For
267 improving GC performance, using
268 <option>-H</option><replaceable>size</replaceable> is
269 usually a better bet than
270 <option>-A</option><replaceable>size</replaceable>.</para>
276 <option>-I</option><replaceable>seconds</replaceable>
277 <indexterm><primary><option>-I</option></primary>
278 <secondary>RTS option</secondary>
280 <indexterm><primary>idle GC</primary>
284 <para>(default: 0.3) In the threaded and SMP versions of the RTS (see
285 <option>-threaded</option>, <xref linkend="options-linker" />), a
286 major GC is automatically performed if the runtime has been idle
287 (no Haskell computation has been running) for a period of time.
288 The amount of idle time which must pass before a GC is performed is
289 set by the <option>-I</option><replaceable>seconds</replaceable>
290 option. Specifying <option>-I0</option> disables the idle GC.</para>
292 <para>For an interactive application, it is probably a good idea to
293 use the idle GC, because this will allow finalizers to run and
294 deadlocked threads to be detected in the idle time when no Haskell
295 computation is happening. Also, it will mean that a GC is less
296 likely to happen when the application is busy, and so
297 responsiveness may be improved. However, if the amount of live data in
298 the heap is particularly large, then the idle GC can cause a
299 significant delay, and too small an interval could adversely affect
300 interactive responsiveness.</para>
302 <para>This is an experimental feature, please let us know if it
303 causes problems and/or could benefit from further tuning.</para>
309 <option>-k</option><replaceable>size</replaceable>
310 <indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm>
311 <indexterm><primary>stack, minimum size</primary></indexterm>
314 <para>[Default: 1k] Set the initial stack size for
315 new threads. Thread stacks (including the main thread's
316 stack) live on the heap, and grow as required. The default
317 value is good for concurrent applications with lots of small
318 threads; if your program doesn't fit this model then
319 increasing this option may help performance.</para>
321 <para>The main thread is normally started with a slightly
322 larger heap to cut down on unnecessary stack growth while
323 the program is starting up.</para>
329 <option>-K</option><replaceable>size</replaceable>
330 <indexterm><primary><option>-K</option></primary><secondary>RTS option</secondary></indexterm>
331 <indexterm><primary>stack, maximum size</primary></indexterm>
334 <para>[Default: 8M] Set the maximum stack size for
335 an individual thread to <replaceable>size</replaceable>
336 bytes. This option is there purely to stop the program
337 eating up all the available memory in the machine if it gets
338 into an infinite loop.</para>
344 <option>-m</option><replaceable>n</replaceable>
345 <indexterm><primary><option>-m</option></primary><secondary>RTS option</secondary></indexterm>
346 <indexterm><primary>heap, minimum free</primary></indexterm>
349 <para>Minimum % <replaceable>n</replaceable> of heap
350 which must be available for allocation. The default is
357 <option>-M</option><replaceable>size</replaceable>
358 <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm>
359 <indexterm><primary>heap size, maximum</primary></indexterm>
362 <para>[Default: unlimited] Set the maximum heap size to
363 <replaceable>size</replaceable> bytes. The heap normally
364 grows and shrinks according to the memory requirements of
365 the program. The only reason for having this option is to
366 stop the heap growing without bound and filling up all the
367 available swap space, which at the least will result in the
368 program being summarily killed by the operating
371 <para>The maximum heap size also affects other garbage
372 collection parameters: when the amount of live data in the
373 heap exceeds a certain fraction of the maximum heap size,
374 compacting collection will be automatically enabled for the
375 oldest generation, and the <option>-F</option> parameter
376 will be reduced in order to avoid exceeding the maximum heap
383 <option>-s</option><replaceable>file</replaceable>
384 <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
387 <option>-S</option><replaceable>file</replaceable>
388 <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
391 <para>Write modest (<option>-s</option>) or verbose
392 (<option>-S</option>) garbage-collector statistics into file
393 <replaceable>file</replaceable>. The default
394 <replaceable>file</replaceable> is
395 <filename><replaceable>program</replaceable>.stat</filename>. The
396 <replaceable>file</replaceable> <constant>stderr</constant>
397 is treated specially, with the output really being sent to
398 <constant>stderr</constant>.</para>
400 <para>This option is useful for watching how the storage
401 manager adjusts the heap size based on the current amount of
408 <option>-t<replaceable>file</replaceable></option>
409 <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
412 <para>Write a one-line GC stats summary after running the
413 program. This output is in the same format as that produced
414 by the <option>-Rghc-timing</option> option.</para>
416 <para>As with <option>-s</option>, the default
417 <replaceable>file</replaceable> is
418 <filename><replaceable>program</replaceable>.stat</filename>. The
419 <replaceable>file</replaceable> <constant>stderr</constant>
420 is treated specially, with the output really being sent to
421 <constant>stderr</constant>.</para>
429 <title>RTS options for profiling and parallelism</title>
431 <para>The RTS options related to profiling are described in <xref
432 linkend="rts-options-heap-prof"/>, those for concurrency in
433 <xref linkend="sec-using-concurrent" />, and those for parallelism in
434 <xref linkend="parallel-options"/>.</para>
437 <sect2 id="rts-options-debugging">
438 <title>RTS options for hackers, debuggers, and over-interested
441 <indexterm><primary>RTS options, hacking/debugging</primary></indexterm>
443 <para>These RTS options might be used (a) to avoid a GHC bug,
444 (b) to see “what's really happening”, or
445 (c) because you feel like it. Not recommended for everyday
453 <indexterm><primary><option>-B</option></primary><secondary>RTS option</secondary></indexterm>
456 <para>Sound the bell at the start of each (major) garbage
459 <para>Oddly enough, people really do use this option! Our
460 pal in Durham (England), Paul Callaghan, writes: “Some
461 people here use it for a variety of
462 purposes—honestly!—e.g., confirmation that the
463 code/machine is doing something, infinite loop detection,
464 gauging cost of recently added code. Certain people can even
465 tell what stage [the program] is in by the beep
466 pattern. But the major use is for annoying others in the
467 same office…”</para>
473 <option>-D</option><replaceable>num</replaceable>
474 <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm>
477 <para>An RTS debugging flag; varying quantities of output
478 depending on which bits are set in
479 <replaceable>num</replaceable>. Only works if the RTS was
480 compiled with the <option>DEBUG</option> option.</para>
486 <option>-r</option><replaceable>file</replaceable>
487 <indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm>
488 <indexterm><primary>ticky ticky profiling</primary></indexterm>
489 <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm>
492 <para>Produce “ticky-ticky” statistics at the
493 end of the program run. The <replaceable>file</replaceable>
494 business works just like on the <option>-S</option> RTS
495 option (above).</para>
497 <para>“Ticky-ticky” statistics are counts of
498 various program actions (updates, enters, etc.) The program
499 must have been compiled using
500 <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
501 (a.k.a. “ticky-ticky profiling”), and, for it to
502 be really useful, linked with suitable system libraries.
503 Not a trivial undertaking: consult the installation guide on
504 how to set things up for easy “ticky-ticky”
505 profiling. For more information, see <xref
506 linkend="ticky-ticky"/>.</para>
513 <indexterm><primary><option>-xc</option></primary><secondary>RTS option</secondary></indexterm>
516 <para>(Only available when the program is compiled for
517 profiling.) When an exception is raised in the program,
518 this option causes the current cost-centre-stack to be
519 dumped to <literal>stderr</literal>.</para>
521 <para>This can be particularly useful for debugging: if your
522 program is complaining about a <literal>head []</literal>
523 error and you haven't got a clue which bit of code is
524 causing it, compiling with <literal>-prof
525 -auto-all</literal> and running with <literal>+RTS -xc
526 -RTS</literal> will tell you exactly the call stack at the
527 point the error was raised.</para>
529 <para>The output contains one line for each exception raised
530 in the program (the program might raise and catch several
531 exceptions during its execution), where each line is of the
535 < cc<subscript>1</subscript>, ..., cc<subscript>n</subscript> >
537 <para>each <literal>cc</literal><subscript>i</subscript> is
538 a cost centre in the program (see <xref
539 linkend="cost-centres"/>), and the sequence represents the
540 “call stack” at the point the exception was
541 raised. The leftmost item is the innermost function in the
542 call stack, and the rightmost item is the outermost
551 <indexterm><primary><option>-Z</option></primary><secondary>RTS option</secondary></indexterm>
554 <para>Turn <emphasis>off</emphasis> “update-frame
555 squeezing” at garbage-collection time. (There's no
556 particularly good reason to turn it off, except to ensure
557 the accuracy of certain data collected regarding thunk entry
565 <sect2 id="rts-hooks">
566 <title>“Hooks” to change RTS behaviour</title>
568 <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
569 <indexterm><primary>RTS hooks</primary></indexterm>
570 <indexterm><primary>RTS behaviour, changing</primary></indexterm>
572 <para>GHC lets you exercise rudimentary control over the RTS
573 settings for any given program, by compiling in a
574 “hook” that is called by the run-time system. The RTS
575 contains stub definitions for all these hooks, but by writing your
576 own version and linking it on the GHC command line, you can
577 override the defaults.</para>
579 <para>Owing to the vagaries of DLL linking, these hooks don't work
580 under Windows when the program is built dynamically.</para>
582 <para>The hook <literal>ghc_rts_opts</literal><indexterm><primary><literal>ghc_rts_opts</literal></primary>
583 </indexterm>lets you set RTS
584 options permanently for a given program. A common use for this is
585 to give your program a default heap and/or stack size that is
586 greater than the default. For example, to set <literal>-H128m
587 -K1m</literal>, place the following definition in a C source
591 char *ghc_rts_opts = "-H128m -K1m";
594 <para>Compile the C file, and include the object file on the
595 command line when you link your Haskell program.</para>
597 <para>These flags are interpreted first, before any RTS flags from
598 the <literal>GHCRTS</literal> environment variable and any flags
599 on the command line.</para>
601 <para>You can also change the messages printed when the runtime
602 system “blows up,” e.g., on stack overflow. The hooks
603 for these are as follows:</para>
609 <function>void OutOfHeapHook (unsigned long, unsigned long)</function>
610 <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
613 <para>The heap-overflow message.</para>
619 <function>void StackOverflowHook (long int)</function>
620 <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
623 <para>The stack-overflow message.</para>
629 <function>void MallocFailHook (long int)</function>
630 <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
633 <para>The message printed if <function>malloc</function>
639 <para>For examples of the use of these hooks, see GHC's own
641 <filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
647 ;;; Local Variables: ***
649 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***