1 <Sect1 id="runtime-control">
2 <Title>Running a compiled program
6 <IndexTerm><Primary>runtime control of Haskell programs</Primary></IndexTerm>
7 <IndexTerm><Primary>running, compiled program</Primary></IndexTerm>
8 <IndexTerm><Primary>RTS options</Primary></IndexTerm>
12 To make an executable program, the GHC system compiles your code and
13 then links it with a non-trivial runtime system (RTS), which handles
14 storage management, profiling, etc.
18 You have some control over the behaviour of the RTS, by giving special
19 command-line arguments to your program.
23 When your Haskell program starts up, its RTS extracts command-line
24 arguments bracketed between <Option>+RTS</Option><IndexTerm><Primary>+RTS option</Primary></IndexTerm> and
25 <Option>-RTS</Option><IndexTerm><Primary>-RTS option</Primary></IndexTerm> as its own. For example:
31 % ./a.out -f +RTS -p -S -RTS -h foo bar
37 The RTS will snaffle <Option>-p -S</Option> for itself, and the remaining arguments
38 <Option>-f -h foo bar</Option> will be handed to your program if/when it calls
39 <Function>System.getArgs</Function>.
43 No <Option>-RTS</Option> option is required if the runtime-system options extend to
44 the end of the command line, as in this example:
50 % hls -ltr /usr/etc +RTS -A5m
56 If you absolutely positively want all the rest of the options in a
57 command line to go to the program (and not the RTS), use a
58 <Option>--RTS</Option><IndexTerm><Primary>--RTS option</Primary></IndexTerm>.
62 As always, for RTS options that take <Literal><size></Literal>s: If the last
63 character of <Literal>size</Literal> is a K or k, multiply by 1000; if an M or m, by
64 1,000,000; if a G or G, by 1,000,000,000. (And any wraparound in the
65 counters is <Emphasis>your</Emphasis> fault!)
69 Giving a <Option>+RTS -f</Option><IndexTerm><Primary>-f RTS option</Primary></IndexTerm> option will print out the
70 RTS options actually available in your program (which vary, depending
75 NOTE: to send RTS options to the compiler itself, you need to prefix
76 the option with <Option>-optCrts</Option>, eg. to increase the maximum heap size for
77 a compilation to 128M, you would add <Option>-optCrts-M128m</Option> to the command
78 line. The compiler understands some options directly without needing
79 <Option>-optCrts</Option>: these are <Option>-H</Option> and <Option>-K</Option>.
82 <Sect2 id="rts-options-gc">
83 <Title>RTS options to control the garbage-collector
87 <IndexTerm><Primary>RTS options, garbage-collection</Primary></IndexTerm>
91 There are several options to give you precise control over garbage
92 collection. Hopefully, you won't need any of these in normal
93 operation, but there are several things that can be tweaked for
101 <Term><Option>-A<size></Option>:</Term>
104 <IndexTerm><Primary>-A<size> RTS option</Primary></IndexTerm>
105 <IndexTerm><Primary>allocation area, size</Primary></IndexTerm>
109 [Default: 256k] Set the allocation area size used by the garbage
110 collector. The allocation area (actually generation 0 step 0) is
111 fixed and is never resized (unless you use <Option>-H</Option>, below).
115 Increasing the allocation area size may or may not give better
116 performance (a bigger allocation area means worse cache behaviour but
117 fewer garbage collections and less promotion).
121 With only 1 generation (<Option>-G1</Option>) the <Option>-A</Option> option specifies the
122 minimum allocation area, since the actual size of the allocation area
123 will be resized according to the amount of data in the heap (see
124 <Option>-F</Option>, below).
129 <Term><Option>-F<factor></Option>:</Term>
132 <IndexTerm><Primary>-F<factor> RTS option</Primary></IndexTerm>
133 <IndexTerm><Primary>heap size, factor</Primary></IndexTerm>
137 [Default: 2] This option controls the amount of memory reserved for
138 the older generations (and in the case of a two space collector the
139 size of the allocation area) as a factor of the amount of live data.
140 For example, if there was 2M of live data in the oldest generation
141 when we last collected it, then by default we'll wait until it grows
142 to 4M before collecting it again.
146 The default seems to work well here. If you have plenty of memory, it
147 is usually better to use <Option>-H<size></Option> than to increase
148 <Option>-F<factor></Option>.
152 The <Option>-F</Option> setting will be automatically reduced by the garbage
153 collector when the maximum heap size (the <Option>-M<size></Option> setting)
159 <Term><Option>-G<generations></Option>:</Term>
162 <IndexTerm><Primary>-G<generations> RTS option</Primary></IndexTerm>
163 <IndexTerm><Primary>generations, number of</Primary></IndexTerm>
167 [Default: 2] Set the number of generations used by the garbage
168 collector. The default of 2 seems to be good, but the garbage
169 collector can support any number of generations. Anything larger than
170 about 4 is probably not a good idea unless your program runs for a
171 <Emphasis>long</Emphasis> time, because the oldest generation will never get
176 Specifying 1 generation with <Option>+RTS -G1</Option> gives you a simple 2-space
177 collector, as you would expect. In a 2-space collector, the <Option>-A</Option>
178 option (see above) specifies the <Emphasis>minimum</Emphasis> allocation area size,
179 since the allocation area will grow with the amount of live data in
180 the heap. In a multi-generational collector the allocation area is a
181 fixed size (unless you use the <Option>-H</Option> option, see below).
186 <Term><Option>-H<size></Option>:</Term>
189 <IndexTerm><Primary>-H<size> RTS option</Primary></IndexTerm>
190 <IndexTerm><Primary>heap size, suggested</Primary></IndexTerm>
194 [Default: 0] This option provides a "suggested heap size" for the
195 garbage collector. The garbage collector will use about this much
196 memory until the program residency grows and the heap size needs to be
197 expanded to retain reasonable performance.
201 By default, the heap will start small, and grow and shrink as
202 necessary. This can be bad for performance, so if you have plenty of
203 memory it's worthwhile supplying a big <Option>-H<size></Option>. For
204 improving GC performance, using <Option>-H<size></Option> is usually a better
205 bet than <Option>-A<size></Option>.
210 <Term><Option>-k<size></Option>:</Term>
213 <IndexTerm><Primary>-k<size> RTS option</Primary></IndexTerm>
214 <IndexTerm><Primary>stack, minimum size</Primary></IndexTerm>
218 [Default: 1k] Set the initial stack size for new threads. Thread
219 stacks (including the main thread's stack) live on the heap, and grow
220 as required. The default value is good for concurrent applications
221 with lots of small threads; if your program doesn't fit this model
222 then increasing this option may help performance.
226 The main thread is normally started with a slightly larger heap to cut
227 down on unnecessary stack growth while the program is starting up.
232 <Term><Option>-K<size></Option>:</Term>
235 <IndexTerm><Primary>-K<size> RTS option</Primary></IndexTerm>
236 <IndexTerm><Primary>stack, maximum size</Primary></IndexTerm>
240 [Default: 1M] Set the maximum stack size for an individual thread to
241 <Literal><size></Literal> bytes. This option is there purely to stop the program
242 eating up all the available memory in the machine if it gets into an
248 <Term><Option>-m<n></Option>:</Term>
251 <IndexTerm><Primary>-m<n> RTS option</Primary></IndexTerm>
252 Minimum % <Literal><n></Literal> of heap which must be available for allocation.
253 The default is 3%.
254 <IndexTerm><Primary>heap, minimum free</Primary></IndexTerm>
259 <Term><Option>-M<size></Option>:</Term>
262 <IndexTerm><Primary>-M<size> RTS option</Primary></IndexTerm>
263 <IndexTerm><Primary>heap size, maximum</Primary></IndexTerm>
267 [Default: 64M] Set the maximum heap size to <Literal><size></Literal> bytes. The heap
268 normally grows and shrinks according to the memory requirements of the
269 program. The only reason for having this option is to stop the heap
270 growing without bound and filling up all the available swap space,
271 which at the least will result in the program being summarily killed
272 by the operating system.
277 <Term><Option>-s<file></Option> or <Option>-S<file></Option>:</Term>
280 <IndexTerm><Primary>-S<file> RTS option</Primary></IndexTerm>
281 <IndexTerm><Primary>-s<file> RTS option</Primary></IndexTerm>
282 Write modest (<Option>-s</Option>) or verbose (<Option>-S</Option>) garbage-collector
283 statistics into file <Filename><file></Filename>. The default <Filename><file></Filename> is
284 <Filename><program>@.stat</Filename>. The <Filename><file></Filename> <Constant>stderr</Constant> is treated
285 specially, with the output really being sent to <Constant>stderr</Constant>.
289 This option is useful for watching how the storage manager adjusts the
290 heap size based on the current amount of live data.
300 <Title>RTS options for profiling and Concurrent/Parallel Haskell</Title>
303 The RTS options related to profiling are described in <XRef LinkEnd="prof-rts-options">; and those for concurrent/parallel stuff, in
304 <XRef LinkEnd="parallel-rts-opts">.
310 <Title>RTS options for hackers, debuggers, and over-interested souls</Title>
313 <IndexTerm><Primary>RTS options, hacking/debugging</Primary></IndexTerm>
317 These RTS options might be used (a) to avoid a GHC bug, (b) to see
318 ``what's really happening'', or (c) because you feel like it. Not
319 recommended for everyday use!
326 <Term><Option>-B</Option>:</Term>
329 <IndexTerm><Primary>-B RTS option</Primary></IndexTerm>
330 Sound the bell at the start of each (major) garbage collection.
334 Oddly enough, people really do use this option! Our pal in Durham
335 (England), Paul Callaghan, writes: ``Some people here use it for a
336 variety of purposes—honestly!—e.g., confirmation that the
337 code/machine is doing something, infinite loop detection, gauging cost
338 of recently added code. Certain people can even tell what stage [the
339 program] is in by the beep pattern. But the major use is for annoying
340 others in the same office…''
345 <Term><Option>-r<file></Option>:</Term>
348 <IndexTerm><Primary>-r <file> RTS option</Primary></IndexTerm>
349 <IndexTerm><Primary>ticky ticky profiling</Primary></IndexTerm>
350 Produce ``ticky-ticky'' statistics at the end of the program run.
351 The <Filename><file></Filename> business works just like on the <Option>-S</Option> RTS option (above).
355 ``Ticky-ticky'' statistics are counts of various program actions
356 (updates, enters, etc.) The program must have been compiled using
357 <Option>-ticky</Option><IndexTerm><Primary>-ticky option</Primary></IndexTerm> (a.k.a. ``ticky-ticky profiling''),
358 and, for it to be really useful, linked with suitable system
359 libraries. Not a trivial undertaking: consult the installation guide
360 on how to set things up for easy ``ticky-ticky'' profiling. For more
361 information, see <XRef LinkEnd="ticky-ticky">.
366 <Term><Option>-D<num></Option>:</Term>
369 <IndexTerm><Primary>-D RTS option</Primary></IndexTerm>
370 An RTS debugging flag; varying quantities of output depending on which
371 bits are set in <Literal><num></Literal>. Only works if the RTS was compiled with the
372 <Option>DEBUG</Option> option.
377 <Term><Option>-Z</Option>:</Term>
380 <IndexTerm><Primary>-Z RTS option</Primary></IndexTerm>
381 Turn <Emphasis>off</Emphasis> ``update-frame squeezing'' at garbage-collection
382 time. (There's no particularly good reason to turn it off, except to
383 ensure the accuracy of certain data collected regarding thunk entry
393 <Sect2 id="rts-hooks">
394 <Title>``Hooks'' to change RTS behaviour
398 <IndexTerm><Primary>hooks, RTS</Primary></IndexTerm>
399 <IndexTerm><Primary>RTS hooks</Primary></IndexTerm>
400 <IndexTerm><Primary>RTS behaviour, changing</Primary></IndexTerm>
404 GHC lets you exercise rudimentary control over the RTS settings for
405 any given program, by compiling in a ``hook'' that is called by the
406 run-time system. The RTS contains stub definitions for all these
407 hooks, but by writing your own version and linking it on the GHC
408 command line, you can override the defaults.
412 The function <Function>defaultsHook</Function><IndexTerm><Primary>defaultHook</Primary></IndexTerm> lets you change various
413 RTS options. The commonest use for this is to give your program a
414 default heap and/or stack size that is greater than the default. For
415 example, to set <Option>-H8m -K1m</Option>:
422 #include "RtsFlags.h"
423 void defaultsHook (void) {
424 RTSflags.GcFlags.stksSize = 1000002 / sizeof(W_);
425 RTSflags.GcFlags.heapSize = 8000002 / sizeof(W_);
432 Don't use powers of two for heap/stack sizes: these are more likely to
433 interact badly with direct-mapped caches. The full set of flags is
434 defined in <Filename>ghc/rts/RtsFlags.h</Filename> the the GHC source tree.
438 You can also change the messages printed when the runtime system
439 ``blows up,'' e.g., on stack overflow. The hooks for these are as
447 <Term><Function>void ErrorHdrHook (FILE *)</Function>:</Term>
450 <IndexTerm><Primary>ErrorHdrHook</Primary></IndexTerm>
451 What's printed out before the message from <Function>error</Function>.
456 <Term><Function>void OutOfHeapHook (unsigned long, unsigned long)</Function>:</Term>
459 <IndexTerm><Primary>OutOfHeapHook</Primary></IndexTerm>
460 The heap-overflow message.
465 <Term><Function>void StackOverflowHook (long int)</Function>:</Term>
468 <IndexTerm><Primary>StackOverflowHook</Primary></IndexTerm>
469 The stack-overflow message.
474 <Term><Function>void MallocFailHook (long int)</Function>:</Term>
477 <IndexTerm><Primary>MallocFailHook</Primary></IndexTerm>
478 The message printed if <Function>malloc</Function> fails.
483 <Term><Function>void PatErrorHdrHook (FILE *)</Function>:</Term>
486 <IndexTerm><Primary>PatErrorHdrHook</Primary></IndexTerm>
487 The message printed if a pattern-match fails (the failures
488 that were not handled by the Haskell programmer).
493 <Term><Function>void PreTraceHook (FILE *)</Function>:</Term>
496 <IndexTerm><Primary>PreTraceHook</Primary></IndexTerm>
497 What's printed out before a <Function>trace</Function> message.
502 <Term><Function>void PostTraceHook (FILE *)</Function>:</Term>
505 <IndexTerm><Primary>PostTraceHook</Primary></IndexTerm>
506 What's printed out after a <Function>trace</Function> message.
514 For example, here is the ``hooks'' code used by GHC itself:
517 #include <stdio.h>
518 #define W_ unsigned long int
522 ErrorHdrHook (FILE *where)
524 fprintf(where, "\n"); /* no "Fail: " */
528 OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
530 fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
531 allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
532 option to increase the total heap size.\n",
538 StackOverflowHook (I_ stack_size) /* in bytes */
540 fprintf(stderr, "GHC stack-space overflow: current size
541 %ld bytes.\nUse the `-K<size>' option to increase it.\n",
546 PatErrorHdrHook (FILE *where)
548 fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
549 This is a compiler bug; please report it to
550 glasgow-haskell-bugs@haskell.org.\n\nFail: ");
554 PreTraceHook (FILE *where)
556 fprintf(where, "\n"); /* not "Trace On" */
560 PostTraceHook (FILE *where)
562 fprintf(where, "\n"); /* not "Trace Off" */