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 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@.
  56
  57 %************************************************************************
  58 %*                                                                      *
  59 <sect2>RTS options to control the garbage-collector
  60 <label id="rts-options-gc">
  61 <p>
  62 <nidx>RTS options, garbage-collection</nidx>
  63 %*                                                                      *
  64 %************************************************************************
  65
  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
  69 maximum performance.
  70
  71 <descrip>
  72 <tag>@-A<size>@:</tag>
  73 <nidx>-A&lt;size&gt; RTS option</nidx>
  74 <nidx>allocation area, size</nidx>
  75
  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).
  79
  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).
  83
  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
  87 <tt/-F/, below).
  88
  89 <tag>@-F<factor>@:</tag>
  90 <nidx>-F&lt;factor&gt; RTS option</nidx>
  91 <nidx>heap size, factor</nidx>
  92
  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.
  99
 100 The default seems to work well here.  If you have plenty of memory, it
 101 is usually better to use <tt/-H&lt;size&gt;/ than to increase
 102 <tt/-F&lt;factor&gt;/.
 103
 104 The <tt/-F/ setting will be automatically reduced by the garbage
 105 collector when the maximum heap size (the <tt/-M&lt;size&gt;/ setting)
 106 is approaching.
 107
 108 <tag>@-G<generations>@:</tag>
 109 <nidx>-G&lt;generations&gt; RTS option</nidx>
 110 <nidx>generations, number of</nidx>
 111
 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
 117 collected.
 118
 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).
 125
 126 <tag>@-H<size>@:</tag>
 127 <nidx>-H&lt;size&gt; RTS option</nidx>
 128 <nidx>heap size, suggested</nidx>
 129
 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.
 134
 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&lt;size&gt/.  For
 138 improving GC performance, using <tt/-H&lt;size&gt/ is usually a better
 139 bet than <tt/-A&lt;size&gt/.
 140
 141 <tag>@-k<size>@:</tag>
 142 <nidx>-k&lt;size&gt; RTS option</nidx>
 143 <nidx>stack, minimum size</nidx>
 144
 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.
 150
 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.
 153
 154 <tag>@-K<size>@:</tag>
 155 <nidx>-K&lt;size&gt; RTS option</nidx>
 156 <nidx>stack, maximum size</nidx>
 157
 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
 161 infinite loop.
 162
 163 <tag>@-m<n>@:</tag>
 164 <nidx>-m&lt;n&gt; RTS option</nidx>
 165 Minimum \% @<n>@ of heap which must be available for allocation.
 166 The default is 3\%.
 167 <nidx>heap, minimum free</nidx>
 168
 169 <tag>@-M<size>@:</tag>
 170 <nidx>-M&lt;size&gt; RTS option</nidx>
 171 <nidx>heap size, maximum</nidx>
 172
 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.
 179
 180 <tag>@-s<file>@ or @-S<file>@:</tag>
 181 <nidx>-S&lt;file&gt; RTS option</nidx>
 182 <nidx>-s&lt;file&gt; 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@.
 187
 188 This option is useful for watching how the storage manager adjusts the
 189 heap size based on the current amount of live data.
 190
 191 % ToDo: --SDM
 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@).
 196
 197 % <tag>@-j<size>@:</tag>
 198 % <nidx>-j&lt;size&gt; 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
 201 % info.)
 202
 203 </descrip>
 204
 205 %************************************************************************
 206 %*                                                                      *
 207 <sect2>RTS options for profiling and Concurrent/Parallel Haskell
 208 <p>
 209 %*                                                                      *
 210 %************************************************************************
 211
 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">.
 217
 218 %************************************************************************
 219 %*                                                                      *
 220 <sect2>RTS options for hackers, debuggers, and over-interested souls
 221 <p>
 222 <nidx>RTS options, hacking/debugging</nidx>
 223 %*                                                                      *
 224 %************************************************************************
 225
 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!
 229
 230 <descrip>
 231 <tag>@-B@:</tag>
 232 <nidx>-B RTS option</nidx>
 233 Sound the bell at the start of each (major) garbage collection.
 234
 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...''
 242
 243 <tag>@-r<file>@:</tag>
 244 <nidx>-r &lt;file&gt; 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).
 248
 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">.
 257
 258 <tag>@-xc@:</tag>
 259 <nidx>-xc RTS option</nidx>
 260 <nidx>cost centre display on exception</nidx>
 261 Display the current cost centre stack whenever an exception is
 262 raised.  The program must have been compiled with profiling turned on:
 263 see Section <ref name="Profiling" id="profiling">.  This feature is
 264 experimental; one day it will display the information only on
 265 <em>uncaught</em> exceptions.
 266
 267 <tag>@-D<num>@:</tag>
 268 <nidx>-D RTS option</nidx>
 269 An RTS debugging flag; varying quantities of output depending on which
 270 bits are set in @<num>@.  Only works if the RTS was compiled with the
 271 @DEBUG@ option.
 272
 273 % Blackholing can't be turned off in new RTS --SDM
 274 %
 275 % <tag>@-N@:</tag>
 276 % <nidx>-N RTS option</nidx>
 277 %
 278 % Normally, the garbage collector black-holes closures which are being
 279 % evaluated, as a space-saving measure.  This option turns off
 280 % blackholing.  You shouldn't ever need to use it.
 281 %
 282 % Historical note: this option used to be used to work around a problem
 283 % with signal handling, where a signal handler might need to evaluate
 284 % blackholed closures.  Signal handlers are now run in a separate
 285 % thread, and don't suffer from this problem.
 286
 287 <tag>@-Z@:</tag>
 288 <nidx>-Z RTS option</nidx>
 289 Turn <em>off</em> ``update-frame squeezing'' at garbage-collection
 290 time.  (There's no particularly good reason to turn it off, except to
 291 ensure the accuracy of certain data collected regarding thunk entry
 292 counts.)
 293 </descrip>
 294
 295 %************************************************************************
 296 %*                                                                      *
 297 <sect2>``Hooks'' to change RTS behaviour
 298 <label id="rts-hooks">
 299 <p>
 300 <nidx>hooks, RTS</nidx>
 301 <nidx>RTS hooks</nidx>
 302 <nidx>RTS behaviour, changing</nidx>
 303 %*                                                                      *
 304 %************************************************************************
 305
 306 GHC lets you exercise rudimentary control over the RTS settings for
 307 any given program, by compiling in a ``hook'' that is called by the
 308 run-time system.  The RTS contains stub definitions for all these
 309 hooks, but by writing your own version and linking it on the GHC
 310 command line, you can override the defaults.
 311
 312 The function @defaultsHook@<nidx>defaultHook</nidx> lets you change various
 313 RTS options.  The commonest use for this is to give your program a
 314 default heap and/or stack size that is greater than the default.  For
 315 example, to set @-H8m -K1m@:
 316
 317 <tscreen><verb>
 318 #include "Rts.h"
 319 #include "RtsFlags.h"
 320 void defaultsHook (void) {
 321    RTSflags.GcFlags.stksSize =  1000002 / sizeof(W_);
 322    RTSflags.GcFlags.heapSize =  8000002 / sizeof(W_);
 323 }
 324 </verb></tscreen>
 325
 326 Don't use powers of two for heap/stack sizes: these are more likely to
 327 interact badly with direct-mapped caches.  The full set of flags is
 328 defined in @ghc/rts/RtsFlags.h@ the the GHC source tree.
 329
 330 You can also change the messages printed when the runtime system
 331 ``blows up,'' e.g., on stack overflow.  The hooks for these are as
 332 follows:
 333
 334 <descrip>
 335 <tag>@void ErrorHdrHook (FILE *)@:</tag>
 336 <nidx>ErrorHdrHook</nidx>
 337 What's printed out before the message from @error@.
 338
 339 <tag>@void OutOfHeapHook (unsigned long, unsigned long)@:</tag>
 340 <nidx>OutOfHeapHook</nidx>
 341 The heap-overflow message.
 342
 343 <tag>@void StackOverflowHook (long int)@:</tag>
 344 <nidx>StackOverflowHook</nidx>
 345 The stack-overflow message.
 346
 347 <tag>@void MallocFailHook (long int)@:</tag>
 348 <nidx>MallocFailHook</nidx>
 349 The message printed if @malloc@ fails.
 350
 351 <tag>@void PatErrorHdrHook (FILE *)@:</tag>
 352 <nidx>PatErrorHdrHook</nidx>
 353 The message printed if a pattern-match fails (the failures
 354 that were not handled by the Haskell programmer).
 355
 356 <tag>@void PreTraceHook (FILE *)@:</tag>
 357 <nidx>PreTraceHook</nidx>
 358 What's printed out before a @trace@ message.
 359
 360 <tag>@void PostTraceHook (FILE *)@:</tag>
 361 <nidx>PostTraceHook</nidx>
 362 What's printed out after a @trace@ message.
 363 </descrip>
 364
 365 For example, here is the ``hooks'' code used by GHC itself:
 366 <tscreen><verb>
 367 #include <stdio.h>
 368 #define W_ unsigned long int
 369 #define I_ long int
 370
 371 void
 372 ErrorHdrHook (FILE *where)
 373 {
 374     fprintf(where, "\n"); /* no "Fail: " */
 375 }
 376
 377 void
 378 OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
 379 {
 380     fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
 381         allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
 382         option to increase the total heap size.\n",
 383         request_size,
 384         heap_size);
 385 }
 386
 387 void
 388 StackOverflowHook (I_ stack_size)    /* in bytes */
 389 {
 390     fprintf(stderr, "GHC stack-space overflow: current size
 391         %ld bytes.\nUse the `-K<size>' option to increase it.\n",
 392         stack_size);
 393 }
 394
 395 void
 396 PatErrorHdrHook (FILE *where)
 397 {
 398     fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
 399         This is a compiler bug; please report it to
 400         glasgow-haskell-bugs@haskell.org.\n\nFail: ");
 401 }
 402
 403 void
 404 PreTraceHook (FILE *where)
 405 {
 406     fprintf(where, "\n"); /* not "Trace On" */
 407 }
 408
 409 void
 410 PostTraceHook (FILE *where)
 411 {
 412     fprintf(where, "\n"); /* not "Trace Off" */
 413 }
 414 </verb></tscreen>