1 %************************************************************************
3 <sect1>Running a compiled program
4 <label id="runtime-control">
6 <nidx>runtime control of Haskell programs</nidx>
7 <nidx>running, compiled program</nidx>
8 <nidx>RTS options</nidx>
10 %************************************************************************
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.
16 You have some control over the behaviour of the RTS, by giving special
17 command-line arguments to your program.
19 When your Haskell program starts up, its RTS extracts command-line
20 arguments bracketed between @+RTS@<nidx>+RTS option</nidx> and
21 @-RTS@<nidx>-RTS option</nidx> as its own. For example:
24 % ./a.out -f +RTS -p -S -RTS -h foo bar
27 The RTS will snaffle @-p -S@ for itself, and the remaining arguments
28 @-f -h foo bar@ will be handed to your program if/when it calls
31 No @-RTS@ option is required if the runtime-system options extend to
32 the end of the command line, as in this example:
35 % hls -ltr /usr/etc +RTS -A5m
38 If you absolutely positively want all the rest of the options in a
39 command line to go to the program (and not the RTS), use a
40 @--RTS@<nidx>--RTS option</nidx>.
42 As always, for RTS options that take @<size>@s: If the last
43 character of @size@ is a K or k, multiply by 1000; if an M or m, by
44 1,000,000; if a G or G, by 1,000,000,000. (And any wraparound in the
45 counters is <em>your</em> fault!)
47 Giving a @+RTS -f@<nidx>-f RTS option</nidx> option will print out the
48 RTS options actually available in your program (which vary, depending
51 NOTE: to send RTS options to the compiler itself, you need to prefix
52 the option with @-optCrts@, eg. to increase the maximum heap size for
53 a compilation to 128M, you would add @-optCrts-M128m@ to the command
54 line. The compiler understands some options directly without needing
55 @-optCrts@: these are @-H@ and @-K@.
57 %************************************************************************
59 <sect2>RTS options to control the garbage-collector
60 <label id="rts-options-gc">
62 <nidx>RTS options, garbage-collection</nidx>
64 %************************************************************************
66 There are several options to give you precise control over garbage
67 collection. Hopefully, you won't need any of these in normal
68 operation, but there are several things that can be tweaked for
72 <tag>@-A<size>@:</tag>
73 <nidx>-A<size> RTS option</nidx>
74 <nidx>allocation area, size</nidx>
76 [Default: 256k] Set the allocation area size used by the garbage
77 collector. The allocation area (actually generation 0 step 0) is
78 fixed and is never resized (unless you use <tt/-H/, below).
80 Increasing the allocation area size may or may not give better
81 performance (a bigger allocation area means worse cache behaviour but
82 fewer garbage collections and less promotion).
84 With only 1 generation (<tt/-G1/) the <tt/-A/ option specifies the
85 minimum allocation area, since the actual size of the allocation area
86 will be resized according to the amount of data in the heap (see
89 <tag>@-F<factor>@:</tag>
90 <nidx>-F<factor> RTS option</nidx>
91 <nidx>heap size, factor</nidx>
93 [Default: 2] This option controls the amount of memory reserved for
94 the older generations (and in the case of a two space collector the
95 size of the allocation area) as a factor of the amount of live data.
96 For example, if there was 2M of live data in the oldest generation
97 when we last collected it, then by default we'll wait until it grows
98 to 4M before collecting it again.
100 The default seems to work well here. If you have plenty of memory, it
101 is usually better to use <tt/-H<size>/ than to increase
102 <tt/-F<factor>/.
104 The <tt/-F/ setting will be automatically reduced by the garbage
105 collector when the maximum heap size (the <tt/-M<size>/ setting)
108 <tag>@-G<generations>@:</tag>
109 <nidx>-G<generations> RTS option</nidx>
110 <nidx>generations, number of</nidx>
112 [Default: 2] Set the number of generations used by the garbage
113 collector. The default of 2 seems to be good, but the garbage
114 collector can support any number of generations. Anything larger than
115 about 4 is probably not a good idea unless your program runs for a
116 <em/long/ time, because the oldest generation will never get
119 Specifying 1 generation with @+RTS -G1@ gives you a simple 2-space
120 collector, as you would expect. In a 2-space collector, the @-A@
121 option (see above) specifies the <em/minimum/ allocation area size,
122 since the allocation area will grow with the amount of live data in
123 the heap. In a multi-generational collector the allocation area is a
124 fixed size (unless you use the <tt/-H/ option, see below).
126 <tag>@-H<size>@:</tag>
127 <nidx>-H<size> RTS option</nidx>
128 <nidx>heap size, suggested</nidx>
130 [Default: 0] This option provides a "suggested heap size" for the
131 garbage collector. The garbage collector will use about this much
132 memory until the program residency grows and the heap size needs to be
133 expanded to retain reasonable performance.
135 By default, the heap will start small, and grow and shrink as
136 necessary. This can be bad for performance, so if you have plenty of
137 memory it's worthwhile supplying a big <tt/-H<size>/. For
138 improving GC performance, using <tt/-H<size>/ is usually a better
139 bet than <tt/-A<size>/.
141 <tag>@-k<size>@:</tag>
142 <nidx>-k<size> RTS option</nidx>
143 <nidx>stack, minimum size</nidx>
145 [Default: 1k] Set the initial stack size for new threads. Thread
146 stacks (including the main thread's stack) live on the heap, and grow
147 as required. The default value is good for concurrent applications
148 with lots of small threads; if your program doesn't fit this model
149 then increasing this option may help performance.
151 The main thread is normally started with a slightly larger heap to cut
152 down on unnecessary stack growth while the program is starting up.
154 <tag>@-K<size>@:</tag>
155 <nidx>-K<size> RTS option</nidx>
156 <nidx>stack, maximum size</nidx>
158 [Default: 1M] Set the maximum stack size for an individual thread to
159 @<size>@ bytes. This option is there purely to stop the program
160 eating up all the available memory in the machine if it gets into an
164 <nidx>-m<n> RTS option</nidx>
165 Minimum \% @<n>@ of heap which must be available for allocation.
167 <nidx>heap, minimum free</nidx>
169 <tag>@-M<size>@:</tag>
170 <nidx>-M<size> RTS option</nidx>
171 <nidx>heap size, maximum</nidx>
173 [Default: 64M] Set the maximum heap size to @<size>@ bytes. The heap
174 normally grows and shrinks according to the memory requirements of the
175 program. The only reason for having this option is to stop the heap
176 growing without bound and filling up all the available swap space,
177 which at the least will result in the program being summarily killed
178 by the operating system.
180 <tag>@-s<file>@ or @-S<file>@:</tag>
181 <nidx>-S<file> RTS option</nidx>
182 <nidx>-s<file> RTS option</nidx>
183 Write modest (@-s@) or verbose (@-S@) garbage-collector
184 statistics into file @<file>@. The default @<file>@ is
185 @<program>@@.stat@. The @<file>@ @stderr@ is treated
186 specially, with the output really being sent to @stderr@.
188 This option is useful for watching how the storage manager adjusts the
189 heap size based on the current amount of live data.
192 %For some garbage collectors (not including the default one, sadly),
193 %you can convert the @-S@ output into a residency graph (in
194 %PostScript), using the @stat2resid@<nidx>stat2resid</nidx> utility in
195 %the GHC distribution (@ghc/utils/stat2resid@).
197 % <tag>@-j<size>@:</tag>
198 % <nidx>-j<size> RTS option</nidx>
199 % Force a major garbage collection every @<size>@ bytes. (Normally
200 % used because you're keen on getting major-GC stats, notably heap residency
205 %************************************************************************
207 <sect2>RTS options for profiling and Concurrent/Parallel Haskell
210 %************************************************************************
212 The RTS options related to profiling are described in Section <ref
213 name="How to control your profiled program at runtime"
214 id="prof-rts-options">; and those for concurrent/parallel stuff, in
215 Section <ref name="RTS options for Concurrent/Parallel Haskell"
216 id="parallel-rts-opts">.
218 %************************************************************************
220 <sect2>RTS options for hackers, debuggers, and over-interested souls
222 <nidx>RTS options, hacking/debugging</nidx>
224 %************************************************************************
226 These RTS options might be used (a)~to avoid a GHC bug, (b)~to see
227 ``what's really happening'', or (c)~because you feel like it. Not
228 recommended for everyday use!
232 <nidx>-B RTS option</nidx>
233 Sound the bell at the start of each (major) garbage collection.
235 Oddly enough, people really do use this option! Our pal in Durham
236 (England), Paul Callaghan, writes: ``Some people here use it for a
237 variety of purposes---honestly!---e.g., confirmation that the
238 code/machine is doing something, infinite loop detection, gauging cost
239 of recently added code. Certain people can even tell what stage [the
240 program] is in by the beep pattern. But the major use is for annoying
241 others in the same office...''
243 <tag>@-r<file>@:</tag>
244 <nidx>-r <file> RTS option</nidx>
245 <nidx>ticky ticky profiling</nidx>
246 Produce ``ticky-ticky'' statistics at the end of the program run.
247 The @<file>@ business works just like on the @-S@ RTS option (above).
249 ``Ticky-ticky'' statistics are counts of various program actions
250 (updates, enters, etc.) The program must have been compiled using
251 @-ticky@<nidx>-ticky option</nidx> (a.k.a. ``ticky-ticky profiling''),
252 and, for it to be really useful, linked with suitable system
253 libraries. Not a trivial undertaking: consult the installation guide
254 on how to set things up for easy ``ticky-ticky'' profiling. For more
255 information, see Section <ref name="Using ``ticky-ticky'' profiling
256 (for implementors)" id="ticky-ticky">.
258 <tag>@-D<num>@:</tag>
259 <nidx>-D RTS option</nidx>
260 An RTS debugging flag; varying quantities of output depending on which
261 bits are set in @<num>@. Only works if the RTS was compiled with the
264 % Blackholing can't be turned off in new RTS --SDM
267 % <nidx>-N RTS option</nidx>
269 % Normally, the garbage collector black-holes closures which are being
270 % evaluated, as a space-saving measure. This option turns off
271 % blackholing. You shouldn't ever need to use it.
273 % Historical note: this option used to be used to work around a problem
274 % with signal handling, where a signal handler might need to evaluate
275 % blackholed closures. Signal handlers are now run in a separate
276 % thread, and don't suffer from this problem.
279 <nidx>-Z RTS option</nidx>
280 Turn <em>off</em> ``update-frame squeezing'' at garbage-collection
281 time. (There's no particularly good reason to turn it off, except to
282 ensure the accuracy of certain data collected regarding thunk entry
286 %************************************************************************
288 <sect2>``Hooks'' to change RTS behaviour
289 <label id="rts-hooks">
291 <nidx>hooks, RTS</nidx>
292 <nidx>RTS hooks</nidx>
293 <nidx>RTS behaviour, changing</nidx>
295 %************************************************************************
297 GHC lets you exercise rudimentary control over the RTS settings for
298 any given program, by compiling in a ``hook'' that is called by the
299 run-time system. The RTS contains stub definitions for all these
300 hooks, but by writing your own version and linking it on the GHC
301 command line, you can override the defaults.
303 The function @defaultsHook@<nidx>defaultHook</nidx> lets you change various
304 RTS options. The commonest use for this is to give your program a
305 default heap and/or stack size that is greater than the default. For
306 example, to set @-H8m -K1m@:
310 #include "RtsFlags.h"
311 void defaultsHook (void) {
312 RTSflags.GcFlags.stksSize = 1000002 / sizeof(W_);
313 RTSflags.GcFlags.heapSize = 8000002 / sizeof(W_);
317 Don't use powers of two for heap/stack sizes: these are more likely to
318 interact badly with direct-mapped caches. The full set of flags is
319 defined in @ghc/rts/RtsFlags.h@ the the GHC source tree.
321 You can also change the messages printed when the runtime system
322 ``blows up,'' e.g., on stack overflow. The hooks for these are as
326 <tag>@void ErrorHdrHook (FILE *)@:</tag>
327 <nidx>ErrorHdrHook</nidx>
328 What's printed out before the message from @error@.
330 <tag>@void OutOfHeapHook (unsigned long, unsigned long)@:</tag>
331 <nidx>OutOfHeapHook</nidx>
332 The heap-overflow message.
334 <tag>@void StackOverflowHook (long int)@:</tag>
335 <nidx>StackOverflowHook</nidx>
336 The stack-overflow message.
338 <tag>@void MallocFailHook (long int)@:</tag>
339 <nidx>MallocFailHook</nidx>
340 The message printed if @malloc@ fails.
342 <tag>@void PatErrorHdrHook (FILE *)@:</tag>
343 <nidx>PatErrorHdrHook</nidx>
344 The message printed if a pattern-match fails (the failures
345 that were not handled by the Haskell programmer).
347 <tag>@void PreTraceHook (FILE *)@:</tag>
348 <nidx>PreTraceHook</nidx>
349 What's printed out before a @trace@ message.
351 <tag>@void PostTraceHook (FILE *)@:</tag>
352 <nidx>PostTraceHook</nidx>
353 What's printed out after a @trace@ message.
356 For example, here is the ``hooks'' code used by GHC itself:
359 #define W_ unsigned long int
363 ErrorHdrHook (FILE *where)
365 fprintf(where, "\n"); /* no "Fail: " */
369 OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
371 fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
372 allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
373 option to increase the total heap size.\n",
379 StackOverflowHook (I_ stack_size) /* in bytes */
381 fprintf(stderr, "GHC stack-space overflow: current size
382 %ld bytes.\nUse the `-K<size>' option to increase it.\n",
387 PatErrorHdrHook (FILE *where)
389 fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
390 This is a compiler bug; please report it to
391 glasgow-haskell-bugs@haskell.org.\n\nFail: ");
395 PreTraceHook (FILE *where)
397 fprintf(where, "\n"); /* not "Trace On" */
401 PostTraceHook (FILE *where)
403 fprintf(where, "\n"); /* not "Trace Off" */