1 %************************************************************************
3 \section[runtime-control]{Controlling the run-time behaviour of your programs}
4 \index{runtime control of Haskell programs}
7 %************************************************************************
9 To make an executable program, the GHC system compiles your code and
10 then links it with a non-trivial runtime system (RTS), which handles
11 storage management, profiling, etc.
13 You have some control over the behaviour of the RTS, by giving special
14 command-line arguments to your program.
16 %You have some control over the behavior of the runtime system, either
17 %by giving special command-line arguments to your program (the usual) or by
18 %building in your own defaults at compile time (the exotic).
20 When your Haskell program starts up, its RTS extracts
21 command-line arguments bracketed between \tr{+RTS}\index{+RTS option}
22 and \tr{-RTS}\index{-RTS option} as its own. For example:
24 % ./a.out -f +RTS -pT -S -RTS -h foo bar
26 The RTS will snaffle \tr{-pT -S} for itself,
27 and the remaining arguments \tr{-f -h foo bar} will be handed
28 to your program if/when it calls @System.getArgs@.
30 No \tr{-RTS} option is required if the runtime-system options extend
31 to the end of the command line, as in this example:
33 % hls -ltr /usr/etc +RTS -H5m
35 If you absolutely positively want all the rest of the options in a
36 command line to go to the program (and not the RTS), use a
37 \tr{--RTS}\index{--RTS option}.
39 As always, for RTS options that take \tr{<size>}s: If the last
40 character of \tr{size} is a K or k, multiply by 1000; if an M or m, by
41 1,000,000; if a G or G, by 1,000,000,000. (And any wraparound in the
42 counters is {\em your} fault!)
44 Giving a \tr{+RTS -f}\index{-f RTS option} option will print out the
45 RTS options actually available in your program (which vary, depending
48 %************************************************************************
50 \subsection{Generally-available RTS options}
51 \index{RTS options, general}
53 %************************************************************************
55 The most important RTS options are:
58 \index{-H<size> RTS option}
59 Set the heap size to \pl{<size>} bytes
63 \index{-K<size> RTS option}
64 Set the stack size to \pl{<size>} bytes [default: 64K].
65 For concurrent/parallel programs, it is the stack size of the main
66 thread; generally speaking, c/p stacks are in heap.
68 Note: if your program seems to be consuming infinite stack space, it
69 is probably in a loop :-) Of course, if stacks are in the heap, make
70 that infinite {\em heap} space...
72 \item[\tr{-s<file>} or \tr{-S<file>}:]
73 \index{-S<file> RTS option}
74 \index{-s<file> RTS option}
75 Write modest (\tr{-s}) or verbose (\tr{-S}) garbage-collector
76 statistics into file \pl{<file>}. The default \pl{<file>} is
77 \pl{<program>}\tr{.stat}. The \pl{<file>} \tr{stderr} is treated
78 specially, with the output really being sent to \tr{stderr}.
80 %Note that \tr{stdout} is flushed before each garbage collection so the
81 %interleaving of \tr{stdout} and the garbage collection statistics will
84 %Note that the same program will typically allocate more space with a
85 %generational collector than with a non-generational collector.
87 The amount of heap allocation will typically increase as the total
88 heap size is reduced. The reason for this odd behaviour is that
89 updates of promoted-to-old-generation objects may require the extra
90 allocation of a new-generation object to ensure that there are never
91 any pointers from the old generation to the new generation.
93 For some garbage collectors (not including the default one, sadly),
94 you can convert the \tr{-S} output into a residency graph (in
95 PostScript), using the \tr{stat2resid}\index{stat2resid} utility in
96 the GHC distribution (\tr{ghc/utils/stat2resid}).
100 Normally, the garbage collector black-holes closures which are being
101 evaluated, as a space-saving measure. That's exactly what you want
102 for ordinary Haskell programs.
104 When signal handlers are present, however, a computation may be
105 abandoned prematurely, leaving black holes behind. If the signal
106 handler shares one of these black-holed closures, disaster can result.
107 Use the \tr{-N} option to prevent black-holing by the garbage
108 collector if you suspect that your signal handlers may share {\em any}
109 subexpressions with the top-level computation. Expect your heap usage
110 to increase, since the lifetimes of some closures may be extended.
113 %************************************************************************
115 \subsection{RTS options to control the garbage-collector}
116 \index{RTS options, garbage-collection}
118 %************************************************************************
120 Besides the \tr{-H} (set heap size) and \tr{-S}/\tr{-s} (GC stats) RTS
121 options, there are several options to give you precise control over
126 \index{-M<n> RTS option}
127 Minimum \% \pl{<n>} of heap which must be available for allocation.
130 \item[\tr{-A<size>}:]
131 \index{-A<size> RTS option}
132 Sets a limit on the size of the allocation area for generational
133 garbage collection to \pl{<size>} bytes (\tr{-A} gives default of 64k). If
134 a negative size is given the size of the allocation is fixed to
135 -\pl{<size>}. For non-generational collectors, it fixes the minimum
136 heap which must be available after a collection, overriding the
137 \tr{-M<n>} RTS option.
139 \item[\tr{-G<size>}:]
140 \index{-G<size> RTS option}
141 Sets the percentage of free space to be promoted before a major
142 collection is invoked to \pl{<size>}\%. The default is 66\%. If a
143 negative size is given it fixes the size of major generation threshold
144 to -\pl{<size>} bytes.
147 \index{-F2s RTS option}
148 Forces a program compiled for generational GC to use two-space copying
149 collection. The two-space collector may outperform the generational
150 collector for programs which have a very low heap residency. It can
151 also be used to generate a statistics file from which a basic heap
152 residency profile can be produced (see Section \ref{stat2resid}).
154 There will still be a small execution overhead imposed by the
155 generational compilation as the test for old generation updates will
156 still be executed (of course none will actually happen). This
157 overhead is typically less than 1\%.
159 \item[\tr{-j<size>}:]
160 \index{-j<size> RTS option}
161 Force a major garbage collection every \pl{<size>} bytes. (Normally
162 used because you're keen on getting major-GC stats, notably heap residency
166 %************************************************************************
168 \subsection{RTS options for profiling and Concurrent/Parallel Haskell}
170 %************************************************************************
172 The RTS options related to profiling are described in
173 \Sectionref{prof-rts-options};
174 and those for concurrent/parallel stuff, in \Sectionref{parallel-rts-opts}.
176 %************************************************************************
178 \subsection{RTS options for hackers, debuggers, and over-interested souls}
179 \index{RTS options, hacking/debugging}
181 %************************************************************************
183 These RTS options might be used (a)~to avoid a GHC bug, (b)~to see
184 ``what's really happening'', or (c)~because you feel like it. Not
185 recommended for everyday use!
189 \index{-B RTS option}
190 Sound the bell at the start of each (major) garbage collection.
192 Oddly enough, people really do use this option! Our pal in Durham
193 (England), Paul Callaghan, writes: ``Some people here use it for a
194 variety of purposes---honestly!---e.g., confirmation that the
195 code/machine is doing something, infinite loop detection, gauging cost
196 of recently added code. Certain people can even tell what stage [the
197 program] is in by the beep pattern. But the major use is for annoying
198 others in the same office...''
201 % Use the ``debugging mini-interpreter'' with sanity-checking; you have
202 % to have an appropriately-compiled version of the prelude, etc.
203 % Goes together nicely with GDB (GNU debugger)...
206 \item[\tr{-r<file>}:]
207 \index{-r <file> RTS option}
208 Produce ``ticky-ticky'' statistics at the end of the program run.
209 The \tr{<file>} business works just like on the \tr{-S} RTS option (above).
211 ``Ticky-ticky'' statistics are counts of various program actions
212 (updates, enters, etc.)
213 The program must have been compiled using
214 \tr{-fstg-reduction-counts}\index{-fstg-reduction-counts option}
215 (a.k.a. ``ticky-ticky profiling''), and, for it to be really useful,
216 linked with suitable system libraries. Not a trivial undertaking:
217 consult the installation guide on how to set things up for
218 easy ``ticky-ticky'' profiling.
221 \index{-T RTS option}
222 An RTS debugging flag; varying quantities of output depending on which bits
223 are set in \pl{<num>}.
226 \index{-Z RTS option}
227 Turn {\em off} ``update-frame squeezing'' at garbage-collection time.
228 (There's no particularly good reason to turn it off.)
231 %************************************************************************
233 \subsection[rts-hooks]{``Hooks'' to change RTS failure messages}
237 %************************************************************************
239 GHC lets you exercise rudimentary control over the messages printed
240 when the runtime system ``blows up,'' e.g., on stack overflow.
242 Simply write some of the following procedures in C and then make sure
243 they get linked in preference to those in the RTS library:
245 \item[\tr{void ErrorHdrHook (FILE *)}:]
247 What's printed out before the message from \tr{error}.
249 \item[\tr{void OutOfHeapHook (unsigned long, unsigned long)}:]
250 \index{OutOfHeapHook}
251 The heap-overflow message.
253 \item[\tr{void StackOverflowHook (long int)}:]
254 \index{StackOverflowHook}
255 The stack-overflow message.
257 \item[\tr{void MallocFailHook (long int)}:]
258 \index{MallocFailHook}
259 The message printed if \tr{malloc} fails.
261 \item[\tr{void PatErrorHdrHook (FILE *)}:]
262 \index{PatErrorHdrHook}
263 The message printed if a pattern-match fails (the failures
264 that were not handled by the Haskell programmer).
266 \item[\tr{void PreTraceHook (FILE *)}:]
268 What's printed out before a \tr{trace} message.
270 \item[\tr{void PostTraceHook (FILE *)}:]
271 \index{PostTraceHook}
272 What's printed out after a \tr{trace} message.
275 For example, here is the ``hooks'' code used by GHC itself:
278 #define W_ unsigned long int
282 ErrorHdrHook (FILE *where)
284 fprintf(where, "\n"); /* no "Fail: " */
288 OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
290 fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
291 allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
292 option to increase the total heap size.\n",
298 StackOverflowHook (I_ stack_size) /* in bytes */
300 fprintf(stderr, "GHC stack-space overflow: current size
301 %ld bytes.\nUse the `-K<size>' option to increase it.\n",
306 PatErrorHdrHook (FILE *where)
308 fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
309 This is a compiler bug; please report it to
310 glasgow-haskell-bugs@dcs.gla.ac.uk.\n\nFail: ");
314 PreTraceHook (FILE *where)
316 fprintf(where, "\n"); /* not "Trace On" */
320 PostTraceHook (FILE *where)
322 fprintf(where, "\n"); /* not "Trace Off" */
326 %************************************************************************
328 %\subsection[rts-control-shell-scripts]{Hiding the runtime-control mess with a shell script}
330 %************************************************************************