ghc/docs/users_guide/runtime_control.vsgml

   1 %************************************************************************
   2 %*                                                                      *
   3 <sect1>Running a compiled program
   4 <label id="runtime-control">
   5 <p>
   6 <nidx>runtime control of Haskell programs</nidx>
   7 <nidx>running, compiled program</nidx>
   8 <nidx>RTS options</nidx>
   9 %*                                                                      *
  10 %************************************************************************
  11
  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.
  15
  16 You have some control over the behaviour of the RTS, by giving special
  17 command-line arguments to your program.
  18
  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:
  22
  23 <tscreen><verb>
  24 % ./a.out -f +RTS -p -S -RTS -h foo bar
  25 </verb></tscreen>
  26
  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
  29 @System.getArgs@.
  30
  31 No @-RTS@ option is required if the runtime-system options extend to
  32 the end of the command line, as in this example:
  33
  34 <tscreen><verb>
  35 % hls -ltr /usr/etc +RTS -A5m
  36 </verb></tscreen>
  37
  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>.
  41
  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!)
  46
  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
  49 on how you compiled).
  50
  51 %************************************************************************
  52 %*                                                                      *
  53 <sect2>RTS options to control the garbage-collector
  54 <label id="rts-options-gc">
  55 <p>
  56 <nidx>RTS options, garbage-collection</nidx>
  57 %*                                                                      *
  58 %************************************************************************
  59
  60 There are several options to give you precise control over garbage
  61 collection.  Hopefully, you won't need any of these in normal
  62 operation, but there are several things that can be tweaked for
  63 maximum performance.
  64
  65 <descrip>
  66 <tag>@-A<size>@:</tag>
  67 <nidx>-A&lt;size&gt; RTS option</nidx>
  68 <nidx>allocation area, size</nidx>
  69
  70 [Default: 256k] Set the allocation area size used by the garbage
  71 collector.  The allocation area (actually generation 0 step 0) is
  72 fixed and is never resized (unless you use <tt/-H/, below).
  73
  74 Increasing the allocation area size may or may not give better
  75 performance (a bigger allocation area means worse cache behaviour but
  76 fewer garbage collections and less promotion).
  77
  78 With only 1 generation (<tt/-G1/) the <tt/-A/ option specifies the
  79 minimum allocation area, since the actual size of the allocation area
  80 will be resized according to the amount of data in the heap (see
  81 <tt/-F/, below).
  82
  83 <tag>@-F<factor>@:</tag>
  84 <nidx>-F&lt;factor&gt; RTS option</nidx>
  85 <nidx>heap size, factor</nidx>
  86
  87 [Default: 2] This option controls the amount of memory reserved for
  88 the older generations (and in the case of a two space collector the
  89 size of the allocation area) as a factor of the amount of live data.
  90 For example, if there was 2M of live data in the oldest generation
  91 when we last collected it, then by default we'll wait until it grows
  92 to 4M before collecting it again.
  93
  94 The default seems to work well here.  If you have plenty of memory, it
  95 is usually better to use <tt/-H&lt;size&gt;/ than to increase
  96 <tt/-F&lt;factor&gt;/.
  97
  98 The <tt/-F/ setting will be automatically reduced by the garbage
  99 collector when the maximum heap size (the <tt/-M&lt;size&gt;/ setting)
 100 is approaching.
 101
 102 <tag>@-G<generations>@:</tag>
 103 <nidx>-G&lt;generations&gt; RTS option</nidx>
 104 <nidx>generations, number of</nidx>
 105
 106 [Default: 2] Set the number of generations used by the garbage
 107 collector.  The default of 2 seems to be good, but the garbage
 108 collector can support any number of generations.  Anything larger than
 109 about 4 is probably not a good idea unless your program runs for a
 110 <em/long/ time, because the oldest generation will never get
 111 collected.
 112
 113 Specifying 1 generation with @+RTS -G1@ gives you a simple 2-space
 114 collector, as you would expect.  In a 2-space collector, the @-A@
 115 option (see above) specifies the <em/minimum/ allocation area size,
 116 since the allocation area will grow with the amount of live data in
 117 the heap.  In a multi-generational collector the allocation area is a
 118 fixed size (unless you use the <tt/-H/ option, see below).
 119
 120 <tag>@-H<size>@:</tag>
 121 <nidx>-H&lt;size&gt; RTS option</nidx>
 122 <nidx>heap size, suggested</nidx>
 123
 124 [Default: 0] This option provides a "suggested heap size" for the
 125 garbage collector.  The garbage collector will use about this much
 126 memory until the program residency grows and the heap size needs to be
 127 expanded to retain reasonable performance.
 128
 129 By default, the heap will start small, and grow and shrink as
 130 necessary.  This can be bad for performance, so if you have plenty of
 131 memory it's worthwhile supplying a big <tt/-H&lt;size&gt/.  For
 132 improving GC performance, using <tt/-H&lt;size&gt/ is usually a better
 133 bet than <tt/-A&lt;size&gt/.
 134
 135 <tag>@-k<size>@:</tag>
 136 <nidx>-k&lt;size&gt; RTS option</nidx>
 137 <nidx>stack, minimum size</nidx>
 138
 139 [Default: 1k] Set the initial stack size for new threads.  Thread
 140 stacks (including the main thread's stack) live on the heap, and grow
 141 as required.  The default value is good for concurrent applications
 142 with lots of small threads; if your program doesn't fit this model
 143 then increasing this option may help performance.
 144
 145 The main thread is normally started with a slightly larger heap to cut
 146 down on unnecessary stack growth while the program is starting up.
 147
 148 <tag>@-K<size>@:</tag>
 149 <nidx>-K&lt;size&gt; RTS option</nidx>
 150 <nidx>stack, maximum size</nidx>
 151
 152 [Default: 1M] Set the maximum stack size for an individual thread to
 153 @<size>@ bytes.  This option is there purely to stop the program
 154 eating up all the available memory in the machine if it gets into an
 155 infinite loop.
 156
 157 <tag>@-m<n>@:</tag>
 158 <nidx>-m&lt;n&gt; RTS option</nidx>
 159 Minimum \% @<n>@ of heap which must be available for allocation.
 160 The default is 3\%.
 161 <nidx>heap, minimum free</nidx>
 162
 163 <tag>@-M<size>@:</tag>
 164 <nidx>-M&lt;size&gt; RTS option</nidx>
 165 <nidx>heap size, maximum</nidx>
 166
 167 [Default: 64M] Set the maximum heap size to @<size>@ bytes.  The heap
 168 normally grows and shrinks according to the memory requirements of the
 169 program.  The only reason for having this option is to stop the heap
 170 growing without bound and filling up all the available swap space,
 171 which at the least will result in the program being summarily killed
 172 by the operating system.
 173
 174 <tag>@-s<file>@ or @-S<file>@:</tag>
 175 <nidx>-S&lt;file&gt; RTS option</nidx>
 176 <nidx>-s&lt;file&gt; RTS option</nidx>
 177 Write modest (@-s@) or verbose (@-S@) garbage-collector
 178 statistics into file @<file>@. The default @<file>@ is
 179 @<program>@@.stat@. The @<file>@ @stderr@ is treated
 180 specially, with the output really being sent to @stderr@.
 181
 182 This option is useful for watching how the storage manager adjusts the
 183 heap size based on the current amount of live data.
 184
 185 % ToDo: --SDM
 186 %For some garbage collectors (not including the default one, sadly),
 187 %you can convert the @-S@ output into a residency graph (in
 188 %PostScript), using the @stat2resid@<nidx>stat2resid</nidx> utility in
 189 %the GHC distribution (@ghc/utils/stat2resid@).
 190
 191 % <tag>@-F2s@:</tag>
 192 % <nidx>-F2s RTS option</nidx>
 193 %
 194 % Forces a program compiled for generational GC to use two-space copying
 195 % collection. The two-space collector may outperform the generational
 196 % collector for programs which have a very low heap residency. It can
 197 % also be used to generate a statistics file from which a basic heap
 198 % residency profile can be produced (see Section <ref name="stat2resid -
 199 % residency info from GC stats" id="stat2resid">).
 200 %
 201 % There will still be a small execution overhead imposed by the
 202 % generational compilation as the test for old generation updates will
 203 % still be executed (of course none will actually happen).  This
 204 % overhead is typically less than 1\%.
 205 %
 206 % <tag>@-j<size>@:</tag>
 207 % <nidx>-j&lt;size&gt; RTS option</nidx>
 208 % Force a major garbage collection every @<size>@ bytes.  (Normally
 209 % used because you're keen on getting major-GC stats, notably heap residency
 210 % info.)
 211
 212 </descrip>
 213
 214 %************************************************************************
 215 %*                                                                      *
 216 <sect2>RTS options for profiling and Concurrent/Parallel Haskell
 217 <p>
 218 %*                                                                      *
 219 %************************************************************************
 220
 221 The RTS options related to profiling are described in Section <ref
 222 name="How to control your profiled program at runtime"
 223 id="prof-rts-options">; and those for concurrent/parallel stuff, in
 224 Section <ref name="RTS options for Concurrent/Parallel Haskell"
 225 id="parallel-rts-opts">.
 226
 227 %************************************************************************
 228 %*                                                                      *
 229 <sect2>RTS options for hackers, debuggers, and over-interested souls
 230 <p>
 231 <nidx>RTS options, hacking/debugging</nidx>
 232 %*                                                                      *
 233 %************************************************************************
 234
 235 These RTS options might be used (a)~to avoid a GHC bug, (b)~to see
 236 ``what's really happening'', or (c)~because you feel like it.  Not
 237 recommended for everyday use!
 238
 239 <descrip>
 240 <tag>@-B@:</tag>
 241 <nidx>-B RTS option</nidx>
 242 Sound the bell at the start of each (major) garbage collection.
 243
 244 Oddly enough, people really do use this option!  Our pal in Durham
 245 (England), Paul Callaghan, writes: ``Some people here use it for a
 246 variety of purposes---honestly!---e.g., confirmation that the
 247 code/machine is doing something, infinite loop detection, gauging cost
 248 of recently added code. Certain people can even tell what stage [the
 249 program] is in by the beep pattern. But the major use is for annoying
 250 others in the same office...''
 251
 252 <tag>@-r<file>@:</tag>
 253 <nidx>-r &lt;file&gt; RTS option</nidx>
 254 <nidx>ticky ticky profiling</nidx>
 255 Produce ``ticky-ticky'' statistics at the end of the program run.
 256 The @<file>@ business works just like on the @-S@ RTS option (above).
 257
 258 ``Ticky-ticky'' statistics are counts of various program actions
 259 (updates, enters, etc.)  The program must have been compiled using
 260 @-fstg-reduction-counts@<nidx>-fstg-reduction-counts option</nidx>
 261 (a.k.a. ``ticky-ticky profiling''), and, for it to be really useful,
 262 linked with suitable system libraries.  Not a trivial undertaking:
 263 consult the installation guide on how to set things up for easy
 264 ``ticky-ticky'' profiling.
 265
 266 <tag>@-D<num>@:</tag>
 267 <nidx>-D RTS option</nidx>
 268 An RTS debugging flag; varying quantities of output depending on which
 269 bits are set in @<num>@.  Only works if the RTS was compiled with the
 270 @DEBUG@ option.
 271
 272 <tag>@-N@:</tag>
 273 <nidx>-N RTS option</nidx>
 274
 275 Normally, the garbage collector black-holes closures which are being
 276 evaluated, as a space-saving measure.  This option turns off
 277 blackholing.  You shouldn't ever need to use it.
 278
 279 Historical note: this option used to be used to work around a problem
 280 with signal handling, where a signal handler might need to evaluate
 281 blackholed closures.  Signal handlers are now run in a separate
 282 thread, and don't suffer from this problem.
 283
 284 <tag>@-Z@:</tag>
 285 <nidx>-Z RTS option</nidx>
 286 Turn <em>off</em> ``update-frame squeezing'' at garbage-collection time.
 287 (There's no particularly good reason to turn it off.)
 288 </descrip>
 289
 290 %************************************************************************
 291 %*                                                                      *
 292 <sect2>``Hooks'' to change RTS behaviour
 293 <label id="rts-hooks">
 294 <p>
 295 <nidx>hooks, RTS</nidx>
 296 <nidx>RTS hooks</nidx>
 297 <nidx>RTS behaviour, changing</nidx>
 298 %*                                                                      *
 299 %************************************************************************
 300
 301 GHC lets you exercise rudimentary control over the RTS settings for
 302 any given program, by compiling in a ``hook'' that is called by the
 303 run-time system.  The RTS contains stub definitions for all these
 304 hooks, but by writing your own version and linking it on the GHC
 305 command line, you can override the defaults.
 306
 307 The function @defaultsHook@<nidx>defaultHook</nidx> lets you change various
 308 RTS options.  The commonest use for this is to give your program a
 309 default heap and/or stack size that is greater than the default.  For
 310 example, to set @-H8m -K1m@:
 311
 312 <tscreen><verb>
 313 #include "Rts.h"
 314 #include "RtsFlags.h"
 315 void defaultsHook (void) {
 316    RTSflags.GcFlags.stksSize =  1000002 / sizeof(W_);
 317    RTSflags.GcFlags.heapSize =  8000002 / sizeof(W_);
 318 }
 319 </verb></tscreen>
 320
 321 Don't use powers of two for heap/stack sizes: these are more likely to
 322 interact badly with direct-mapped caches.  The full set of flags is
 323 defined in @ghc/rts/RtsFlags.h@ the the GHC source tree.
 324
 325 You can also change the messages printed when the runtime system
 326 ``blows up,'' e.g., on stack overflow.  The hooks for these are as
 327 follows:
 328
 329 <descrip>
 330 <tag>@void ErrorHdrHook (FILE *)@:</tag>
 331 <nidx>ErrorHdrHook</nidx>
 332 What's printed out before the message from @error@.
 333
 334 <tag>@void OutOfHeapHook (unsigned long, unsigned long)@:</tag>
 335 <nidx>OutOfHeapHook</nidx>
 336 The heap-overflow message.
 337
 338 <tag>@void StackOverflowHook (long int)@:</tag>
 339 <nidx>StackOverflowHook</nidx>
 340 The stack-overflow message.
 341
 342 <tag>@void MallocFailHook (long int)@:</tag>
 343 <nidx>MallocFailHook</nidx>
 344 The message printed if @malloc@ fails.
 345
 346 <tag>@void PatErrorHdrHook (FILE *)@:</tag>
 347 <nidx>PatErrorHdrHook</nidx>
 348 The message printed if a pattern-match fails (the failures
 349 that were not handled by the Haskell programmer).
 350
 351 <tag>@void PreTraceHook (FILE *)@:</tag>
 352 <nidx>PreTraceHook</nidx>
 353 What's printed out before a @trace@ message.
 354
 355 <tag>@void PostTraceHook (FILE *)@:</tag>
 356 <nidx>PostTraceHook</nidx>
 357 What's printed out after a @trace@ message.
 358 </descrip>
 359
 360 For example, here is the ``hooks'' code used by GHC itself:
 361 <tscreen><verb>
 362 #include <stdio.h>
 363 #define W_ unsigned long int
 364 #define I_ long int
 365
 366 void
 367 ErrorHdrHook (FILE *where)
 368 {
 369     fprintf(where, "\n"); /* no "Fail: " */
 370 }
 371
 372 void
 373 OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
 374 {
 375     fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
 376         allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
 377         option to increase the total heap size.\n",
 378         request_size,
 379         heap_size);
 380 }
 381
 382 void
 383 StackOverflowHook (I_ stack_size)    /* in bytes */
 384 {
 385     fprintf(stderr, "GHC stack-space overflow: current size
 386         %ld bytes.\nUse the `-K<size>' option to increase it.\n",
 387         stack_size);
 388 }
 389
 390 void
 391 PatErrorHdrHook (FILE *where)
 392 {
 393     fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
 394         This is a compiler bug; please report it to
 395         glasgow-haskell-bugs@dcs.gla.ac.uk.\n\nFail: ");
 396 }
 397
 398 void
 399 PreTraceHook (FILE *where)
 400 {
 401     fprintf(where, "\n"); /* not "Trace On" */
 402 }
 403
 404 void
 405 PostTraceHook (FILE *where)
 406 {
 407     fprintf(where, "\n"); /* not "Trace Off" */
 408 }
 409 </verb></tscreen>