1 <sect1 id="runtime-control">
2 <title>Running a compiled program</title>
4 <indexterm><primary>runtime control of Haskell programs</primary></indexterm>
5 <indexterm><primary>running, compiled program</primary></indexterm>
6 <indexterm><primary>RTS options</primary></indexterm>
8 <para>To make an executable program, the GHC system compiles your
9 code and then links it with a non-trivial runtime system (RTS),
10 which handles storage management, profiling, etc.</para>
12 <para>You have some control over the behaviour of the RTS, by giving
13 special command-line arguments to your program.</para>
15 <para>When your Haskell program starts up, its RTS extracts
16 command-line arguments bracketed between
17 <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm>
19 <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm>
20 as its own. For example:</para>
23 % ./a.out -f +RTS -p -S -RTS -h foo bar
26 <para>The RTS will snaffle <option>-p</option> <option>-S</option>
27 for itself, and the remaining arguments <literal>-f -h foo bar</literal>
28 will be handed to your program if/when it calls
29 <function>System.getArgs</function>.</para>
31 <para>No <option>-RTS</option> option is required if the
32 runtime-system options extend to the end of the command line, as in
36 % hls -ltr /usr/etc +RTS -A5m
39 <para>If you absolutely positively want all the rest of the options
40 in a command line to go to the program (and not the RTS), use a
41 <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.</para>
43 <para>As always, for RTS options that take
44 <replaceable>size</replaceable>s: If the last character of
45 <replaceable>size</replaceable> is a K or k, multiply by 1000; if an
46 M or m, by 1,000,000; if a G or G, by 1,000,000,000. (And any
47 wraparound in the counters is <emphasis>your</emphasis>
50 <para>Giving a <literal>+RTS -f</literal>
51 <indexterm><primary><option>-f</option></primary><secondary>RTS option</secondary></indexterm> option
52 will print out the RTS options actually available in your program
53 (which vary, depending on how you compiled).</para>
55 <para>NOTE: since GHC is itself compiled by GHC, you can change RTS
56 options in the compiler using the normal
57 <literal>+RTS ... -RTS</literal>
58 combination. eg. to increase the maximum heap
59 size for a compilation to 128M, you would add
60 <literal>+RTS -M128m -RTS</literal>
61 to the command line.</para>
63 <sect2 id="rts-options-gc">
64 <title>RTS options to control the garbage-collector</title>
66 <indexterm><primary>RTS options, garbage-collection</primary></indexterm>
68 <para>There are several options to give you precise control over
69 garbage collection. Hopefully, you won't need any of these in
70 normal operation, but there are several things that can be tweaked
71 for maximum performance.</para>
76 <term><option>-A</option><replaceable>size</replaceable></Term>
77 <indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm>
78 <indexterm><primary>allocation area, size</primary></indexterm>
80 <para>[Default: 256k] Set the allocation area size
81 used by the garbage collector. The allocation area
82 (actually generation 0 step 0) is fixed and is never resized
83 (unless you use <option>-H</option>, below).</para>
85 <para>Increasing the allocation area size may or may not
86 give better performance (a bigger allocation area means
87 worse cache behaviour but fewer garbage collections and less
90 <para>With only 1 generation (<option>-G1</option>) the
91 <option>-A</option> option specifies the minimum allocation
92 area, since the actual size of the allocation area will be
93 resized according to the amount of data in the heap (see
94 <option>-F</option>, below).</para>
99 <term><option>-F</option><replaceable>factor</replaceable></Term>
101 <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>
102 <indexterm><primary>heap size, factor</primary></indexterm>
104 <para>[Default: 2] This option controls the amount
105 of memory reserved for the older generations (and in the
106 case of a two space collector the size of the allocation
107 area) as a factor of the amount of live data. For example,
108 if there was 2M of live data in the oldest generation when
109 we last collected it, then by default we'll wait until it
110 grows to 4M before collecting it again.</para>
112 <para>The default seems to work well here. If you have
113 plenty of memory, it is usually better to use
114 <option>-H</option><replaceable>size</replaceable> than to
116 <option>-F</option><replaceable>factor</replaceable>.</para>
118 <para>The <option>-F</option> setting will be automatically
119 reduced by the garbage collector when the maximum heap size
120 (the <option>-M</option><replaceable>size</replaceable>
121 setting) is approaching.</para>
126 <term><option>-G</option><replaceable>generations</replaceable></Term>
127 <indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm>
128 <indexterm><primary>generations, number
129 of</primary></indexterm>
131 <para>[Default: 2] Set the number of generations
132 used by the garbage collector. The default of 2 seems to be
133 good, but the garbage collector can support any number of
134 generations. Anything larger than about 4 is probably not a
135 good idea unless your program runs for a
136 <emphasis>long</emphasis> time, because the oldest
137 generation will hardly ever get collected.</para>
139 <para>Specifying 1 generation with <option>+RTS -G1</option>
140 gives you a simple 2-space collector, as you would expect.
141 In a 2-space collector, the <option>-A</option> option (see
142 above) specifies the <Emphasis>minimum</Emphasis> allocation
143 area size, since the allocation area will grow with the
144 amount of live data in the heap. In a multi-generational
145 collector the allocation area is a fixed size (unless you
146 use the <option>-H</option> option, see below).</para>
151 <term><option>-H</option><replaceable>size</replaceable></term>
152 <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
153 <indexterm><primary>heap size, suggested</primary></indexterm>
155 <para>[Default: 0] This option provides a
156 “suggested heap size” for the garbage collector. The
157 garbage collector will use about this much memory until the
158 program residency grows and the heap size needs to be
159 expanded to retain reasonable performance.</para>
161 <para>By default, the heap will start small, and grow and
162 shrink as necessary. This can be bad for performance, so if
163 you have plenty of memory it's worthwhile supplying a big
164 <option>-H</option><replaceable>size</replaceable>. For
165 improving GC performance, using
166 <option>-H</option><replaceable>size</replaceable> is
167 usually a better bet than
168 <option>-A</option><replaceable>size</replaceable>.</para>
173 <term><option>-k</option><replaceable>size</replaceable></term>
174 <indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm>
175 <indexterm><primary>stack, minimum size</primary></indexterm>
177 <para>[Default: 1k] Set the initial stack size for
178 new threads. Thread stacks (including the main thread's
179 stack) live on the heap, and grow as required. The default
180 value is good for concurrent applications with lots of small
181 threads; if your program doesn't fit this model then
182 increasing this option may help performance.</para>
184 <para>The main thread is normally started with a slightly
185 larger heap to cut down on unnecessary stack growth while
186 the program is starting up.</para>
191 <term><option>-K</option><replaceable>size</replaceable></term>
192 <indexterm><primary><option>-K</option></primary><secondary>RTS option</secondary></indexterm>
193 <indexterm><primary>stack, maximum size</primary></indexterm>
195 <para>[Default: 1M] Set the maximum stack size for
196 an individual thread to <replaceable>size</replaceable>
197 bytes. This option is there purely to stop the program
198 eating up all the available memory in the machine if it gets
199 into an infinite loop.</para>
204 <term><option>-m</option><replaceable>n</replaceable></term>
205 <indexterm><primary><option>-m</option></primary><secondary>RTS option</secondary></indexterm>
206 <indexterm><primary>heap, minimum free</primary></indexterm>
208 <para>Minimum % <replaceable>n</replaceable> of heap
209 which must be available for allocation. The default is
215 <term><option>-M</option><replaceable>size</replaceable></term>
216 <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm>
217 <indexterm><primary>heap size, maximum</primary></indexterm>
219 <para>[Default: 64M] Set the maximum heap size to
220 <replaceable>size</replaceable> bytes. The heap normally
221 grows and shrinks according to the memory requirements of
222 the program. The only reason for having this option is to
223 stop the heap growing without bound and filling up all the
224 available swap space, which at the least will result in the
225 program being summarily killed by the operating
231 <term><option>-s</option><replaceable>file</replaceable></term>
232 <term><option>-S</option><replaceable>file</replaceable></Term>
233 <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
234 <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
236 <para>Write modest (<option>-s</option>) or verbose
237 (<option>-S</option>) garbage-collector statistics into file
238 <replaceable>file</replaceable>. The default
239 <replaceable>file</replaceable> is
240 <Filename><replaceable>program</replaceable>.stat</Filename>. The
241 <replaceable>file</replaceable> <constant>stderr</constant>
242 is treated specially, with the output really being sent to
243 <constant>stderr</constant>.</para>
245 <para>This option is useful for watching how the storage
246 manager adjusts the heap size based on the current amount of
252 <term><option>-t</option></term>
253 <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
255 <para>Write a one-line GC stats summary after running the
256 program. This output is in the same format as that produced
257 by the <option>-Rghc-timing</option> option.</para>
264 <!-- ---------------------------------------------------------------------- -->
266 <title>RTS options for profiling and Concurrent/Parallel Haskell</title>
268 <para>The RTS options related to profiling are described in <XRef
269 LinkEnd="prof-rts-options">; and those for concurrent/parallel
270 stuff, in <XRef LinkEnd="parallel-rts-opts">.</para>
273 <!-- ---------------------------------------------------------------------- -->
275 <title>RTS options for hackers, debuggers, and over-interested
278 <indexterm><primary>RTS options, hacking/debugging</primary></indexterm>
280 <para>These RTS options might be used (a) to avoid a GHC bug,
281 (b) to see “what's really happening”, or
282 (c) because you feel like it. Not recommended for everyday
288 <term><option>-B</option></term>
289 <indexterm><primary><option>-B</option></primary><secondary>RTS option</secondary></indexterm>
291 <para>Sound the bell at the start of each (major) garbage
294 <para>Oddly enough, people really do use this option! Our
295 pal in Durham (England), Paul Callaghan, writes: “Some
296 people here use it for a variety of
297 purposes—honestly!—e.g., confirmation that the
298 code/machine is doing something, infinite loop detection,
299 gauging cost of recently added code. Certain people can even
300 tell what stage [the program] is in by the beep
301 pattern. But the major use is for annoying others in the
302 same office…”</para>
307 <term><option>-D</option><replaceable>num</replaceable></term>
308 <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm>
310 <para>An RTS debugging flag; varying quantities of output
311 depending on which bits are set in
312 <replaceable>num</replaceable>. Only works if the RTS was
313 compiled with the <option>DEBUG</option> option.</para>
318 <term><option>-r</option><replaceable>file</replaceable></term>
319 <indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm>
320 <indexterm><primary>ticky ticky profiling</primary></indexterm>
321 <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm>
323 <para>Produce “ticky-ticky” statistics at the
324 end of the program run. The <replaceable>file</replaceable>
325 business works just like on the <option>-S</option> RTS
326 option (above).</para>
328 <para>“Ticky-ticky” statistics are counts of
329 various program actions (updates, enters, etc.) The program
330 must have been compiled using
331 <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
332 (a.k.a. “ticky-ticky profiling”), and, for it to
333 be really useful, linked with suitable system libraries.
334 Not a trivial undertaking: consult the installation guide on
335 how to set things up for easy “ticky-ticky”
336 profiling. For more information, see <XRef
337 LinkEnd="ticky-ticky">.</para>
341 <varlistentry id="stack-trace-option">
342 <term><option>-xc</option></term>
343 <indexterm><primary><option>-xc</option></primary><secondary>RTS
344 option</secondary></indexterm>
346 <para>(Only available when the program is compiled for
347 profiling.) When an exception is raised in the program,
348 this option causes the current cost-centre-stack to be
349 dumped to <literal>stderr</literal>.</para>
351 <para>This can be particularly useful for debugging: if your
352 program is complaining about a <literal>head []</literal>
353 error and you haven't got a clue which bit of code is
354 causing it, compiling with <literal>-prof
355 -auto-all</literal> and running with <literal>+RTS -xc
356 -RTS</literal> will tell you exactly the call stack at the
357 point the error was raised.</para>
362 <term><option>-Z</option></term>
363 <indexterm><primary><option>-Z</option></primary><secondary>RTS
364 option</secondary></indexterm>
366 <para>Turn <emphasis>off</emphasis> “update-frame
367 squeezing” at garbage-collection time. (There's no
368 particularly good reason to turn it off, except to ensure
369 the accuracy of certain data collected regarding thunk entry
377 <sect2 id="rts-hooks">
378 <title>“Hooks” to change RTS behaviour</title>
380 <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
381 <indexterm><primary>RTS hooks</primary></indexterm>
382 <indexterm><primary>RTS behaviour, changing</primary></indexterm>
384 <para>GHC lets you exercise rudimentary control over the RTS
385 settings for any given program, by compiling in a
386 “hook” that is called by the run-time system. The RTS
387 contains stub definitions for all these hooks, but by writing your
388 own version and linking it on the GHC command line, you can
389 override the defaults.</para>
391 <para>Owing to the vagaries of DLL linking, these hooks don't work
392 under Windows when the program is built dynamically.</para>
395 <Function>defaultsHook</Function><indexterm><primary><function>defaultHook</function></primary></indexterm>
396 lets you change various RTS options. The commonest use for this
397 is to give your program a default heap and/or stack size that is
398 greater than the default. For example, to set
399 <literal>-M128m -K1m</literal>:</para>
403 #include "RtsFlags.h"
404 void defaultsHook (void) {
405 RtsFlags.GcFlags.maxStkSize = 1000002 / sizeof(W_);
406 RtsFlags.GcFlags.maxHeapSize = 128*1024*1024 / BLOCK_SIZE_W;
410 <para>Don't use powers of two for heap/stack sizes: these are more
411 likely to interact badly with direct-mapped caches. The full set
412 of flags is defined in <Filename>ghc/rts/RtsFlags.h</Filename> the
413 the GHC source tree.</para>
415 <para>You can also change the messages printed when the runtime
416 system “blows up,” e.g., on stack overflow. The hooks
417 for these are as follows:</para>
422 <term><Function>void ErrorHdrHook (FILE *)</function></term>
423 <indexterm><primary><function>ErrorHdrHook</function></primary></indexterm>
425 <para>What's printed out before the message from
426 <function>error</function>.</para>
431 <term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term>
432 <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
434 <para>The heap-overflow message.</para>
439 <term><function>void StackOverflowHook (long int)</function></term>
440 <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
442 <para>The stack-overflow message.</para>
447 <term><function>void MallocFailHook (long int)</function></term>
448 <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
450 <para>The message printed if <Function>malloc</Function>
456 <term><function>void PatErrorHdrHook (FILE *)</function></term>
457 <indexterm><primary><function>PatErrorHdrHook</function></primary></indexterm>
459 <para>The message printed if a pattern-match fails (the
460 failures that were not handled by the Haskell
466 <term><function>void PreTraceHook (FILE *)</function></term>
467 <indexterm><primary><function>PreTraceHook</function></primary></indexterm>
469 <para>What's printed out before a <Function>trace</Function>
475 <term><function>void PostTraceHook (FILE *)</function></term>
476 <indexterm><primary><function>PostTraceHook</function></primary></indexterm>
478 <para>What's printed out after a <Function>trace</Function>
484 <para>For example, here is the “hooks” code used by
489 #include "../rts/RtsFlags.h"
495 RtsFlags.GcFlags.heapSizeSuggestion = 6*1024*1024 / BLOCK_SIZE;
496 RtsFlags.GcFlags.maxStkSize = 8*1024*1024 / sizeof(W_);
497 RtsFlags.GcFlags.giveStats = COLLECT_GC_STATS;
498 RtsFlags.GcFlags.statsFile = stderr;
502 ErrorHdrHook (long fd)
509 PatErrorHdrHook (long fd)
511 const char msg[]="\n*** Pattern-matching error within GHC!\n\nThis is a compiler bug; please report it to glasgow-haskell-bugs@haskell.org.\n\nFail:";
512 write(fd,msg,sizeof(msg)-1);
516 PreTraceHook (long fd)
518 const char msg[]="\n";
519 write(fd,msg,sizeof(msg)-1);
523 PostTraceHook (long fd)
526 const char msg[]="\n";
527 write(fd,msg,sizeof(msg)-1);
536 ;;; Local Variables: ***
538 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***