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