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 -pT -S -RTS -h foo bar
  25 </verb></tscreen>
  26
  27 The RTS will snaffle @-pT -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 -H5m
  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>Generally-available RTS options
  54 <p>
  55 <nidx>RTS options, general</nidx>
  56 %*                                                                      *
  57 %************************************************************************
  58
  59 The most important RTS options are:
  60 <descrip>
  61 <tag>@-H<size>@:</tag>
  62 <nidx>-H&lt;size&gt; RTS option</nidx>
  63 Set the heap size to @<size>@ bytes
  64 [default: 4M].
  65
  66 <tag>@-K<size>@:</tag>
  67 <nidx>-K&lt;size&gt; RTS option</nidx>
  68 Set the stack size to @<size>@ bytes [default: 64K].
  69 For concurrent/parallel programs, it is the stack size of the main
  70 thread; generally speaking, c/p stacks are in heap.
  71
  72 Note: if your program seems to be consuming infinite stack space, it
  73 is probably in a loop :-) Of course, if stacks are in the heap, make
  74 that infinite <em>heap</em> space...
  75
  76 <tag>@-s<file>@ or @-S<file>@:</tag>
  77 <nidx>-S&lt;file&gt; RTS option</nidx>
  78 <nidx>-s&lt;file&gt; RTS option</nidx>
  79 Write modest (@-s@) or verbose (@-S@) garbage-collector
  80 statistics into file @<file>@. The default @<file>@ is
  81 @<program>@@.stat@. The @<file>@ @stderr@ is treated
  82 specially, with the output really being sent to @stderr@.
  83
  84 The amount of heap allocation will typically increase as the total
  85 heap size is reduced.  The reason for this odd behaviour is that
  86 updates of promoted-to-old-generation objects may require the extra
  87 allocation of a new-generation object to ensure that there are never
  88 any pointers from the old generation to the new generation.
  89
  90 For some garbage collectors (not including the default one, sadly),
  91 you can convert the @-S@ output into a residency graph (in
  92 PostScript), using the @stat2resid@<nidx>stat2resid</nidx> utility in
  93 the GHC distribution (@ghc/utils/stat2resid@).
  94
  95 <tag>@-N@:</tag>
  96 <nidx>-N RTS option</nidx>
  97 Normally, the garbage collector black-holes closures which are being
  98 evaluated, as a space-saving measure.  That's exactly what you want
  99 for ordinary Haskell programs.
 100
 101 When signal handlers are present, however, a computation may be
 102 abandoned prematurely, leaving black holes behind.  If the signal
 103 handler shares one of these black-holed closures, disaster can result.
 104 Use the @-N@ option to prevent black-holing by the garbage collector
 105 if you suspect that your signal handlers may share <em>any</em>
 106 subexpressions with the top-level computation.  Expect your heap usage
 107 to increase, since the lifetimes of some closures may be extended.
 108 </descrip>
 109
 110 %************************************************************************
 111 %*                                                                      *
 112 <sect2>RTS options to control the garbage-collector
 113 <p>
 114 <nidx>RTS options, garbage-collection</nidx>
 115 %*                                                                      *
 116 %************************************************************************
 117
 118 Besides the @-H@ (set heap size) and @-S@/@-s@ (GC stats) RTS
 119 options, there are several options to give you precise control over
 120 garbage collection.
 121
 122 <descrip>
 123 <tag>@-M<n>@:</tag>
 124 <nidx>-M&lt;n&gt; RTS option</nidx>
 125 Minimum \% @<n>@ of heap which must be available for allocation.
 126 The default is 3\%.
 127
 128 <tag>@-A<size>@:</tag>
 129 <nidx>-A&lt;size&gt; RTS option</nidx>
 130 Sets a limit on the size of the allocation area for generational
 131 garbage collection to @<size>@ bytes (@-A@ gives default of 64k). If
 132 a negative size is given the size of the allocation is fixed to
 133 -@<size>@. For non-generational collectors, it fixes the minimum
 134 heap which must be available after a collection, overriding the
 135 @-M<n>@ RTS option.
 136
 137 <tag>@-G<size>@:</tag>
 138 <nidx>-G&lt;size&gt; RTS option</nidx>
 139 Sets the percentage of free space to be promoted before a major
 140 collection is invoked to @<size>@\%. The default is 66\%. If a
 141 negative size is given it fixes the size of major generation threshold
 142 to -@<size>@ bytes.
 143
 144 <tag>@-F2s@:</tag> <nidx>-F2s RTS option</nidx> Forces a program
 145 compiled for generational GC to use two-space copying collection. The
 146 two-space collector may outperform the generational collector for
 147 programs which have a very low heap residency. It can also be used to
 148 generate a statistics file from which a basic heap residency profile
 149 can be produced (see Section <ref name="stat2resid - residency info
 150 from GC stats" id="stat2resid">).
 151
 152 There will still be a small execution overhead imposed by the
 153 generational compilation as the test for old generation updates will
 154 still be executed (of course none will actually happen).  This
 155 overhead is typically less than 1\%.
 156
 157 <tag>@-j<size>@:</tag>
 158 <nidx>-j&lt;size&gt; RTS option</nidx>
 159 Force a major garbage collection every @<size>@ bytes.  (Normally
 160 used because you're keen on getting major-GC stats, notably heap residency
 161 info.)
 162 </descrip>
 163
 164 %************************************************************************
 165 %*                                                                      *
 166 <sect2>RTS options for profiling and Concurrent/Parallel Haskell
 167 <p>
 168 %*                                                                      *
 169 %************************************************************************
 170
 171 The RTS options related to profiling are described in Section <ref name="How to control your profiled program at runtime" id="prof-rts-options">; and those for concurrent/parallel stuff, in
 172 Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.
 173
 174 %************************************************************************
 175 %*                                                                      *
 176 <sect2>RTS options for hackers, debuggers, and over-interested souls
 177 <p>
 178 <nidx>RTS options, hacking/debugging</nidx>
 179 %*                                                                      *
 180 %************************************************************************
 181
 182 These RTS options might be used (a)~to avoid a GHC bug, (b)~to see
 183 ``what's really happening'', or (c)~because you feel like it.  Not
 184 recommended for everyday use!
 185
 186 <descrip>
 187 <tag>@-B@:</tag>
 188 <nidx>-B RTS option</nidx>
 189 Sound the bell at the start of each (major) garbage collection.
 190
 191 Oddly enough, people really do use this option!  Our pal in Durham
 192 (England), Paul Callaghan, writes: ``Some people here use it for a
 193 variety of purposes---honestly!---e.g., confirmation that the
 194 code/machine is doing something, infinite loop detection, gauging cost
 195 of recently added code. Certain people can even tell what stage [the
 196 program] is in by the beep pattern. But the major use is for annoying
 197 others in the same office...''
 198
 199 <tag>@-r<file>@:</tag>
 200 <nidx>-r &lt;file&gt; RTS option</nidx>
 201 Produce ``ticky-ticky'' statistics at the end of the program run.
 202 The @<file>@ business works just like on the @-S@ RTS option (above).
 203
 204 ``Ticky-ticky'' statistics are counts of various program actions
 205 (updates, enters, etc.)
 206 The program must have been compiled using
 207 @-fstg-reduction-counts@<nidx>-fstg-reduction-counts option</nidx>
 208 (a.k.a. ``ticky-ticky profiling''), and, for it to be really useful,
 209 linked with suitable system libraries.  Not a trivial undertaking:
 210 consult the installation guide on how to set things up for
 211 easy ``ticky-ticky'' profiling.
 212
 213 <tag>@-T<num>@:</tag>
 214 <nidx>-T RTS option</nidx>
 215 An RTS debugging flag; varying quantities of output depending on which bits
 216 are set in @<num>@.
 217
 218 <tag>@-Z@:</tag>
 219 <nidx>-Z RTS option</nidx>
 220 Turn <em>off</em> ``update-frame squeezing'' at garbage-collection time.
 221 (There's no particularly good reason to turn it off.)
 222 </descrip>
 223
 224 %************************************************************************
 225 %*                                                                      *
 226 <sect2>``Hooks'' to change RTS behaviour
 227 <label id="rts-hooks">
 228 <p>
 229 <nidx>hooks, RTS</nidx>
 230 <nidx>RTS hooks</nidx>
 231 <nidx>RTS behaviour, changing</nidx>
 232 %*                                                                      *
 233 %************************************************************************
 234
 235 GHC lets you exercise rudimentary control over the RTS settings for
 236 any given program, by compiling in a ``hook'' that is called by the
 237 run-time system.  The RTS contains stub definitions for all these
 238 hooks, but by writing your own version and linking it on the GHC
 239 command line, you can override the defaults.
 240
 241 The function @defaultsHook@<nidx>defaultHook</nidx> lets you change various
 242 RTS options.  The commonest use for this is to give your program a
 243 default heap and/or stack size that is greater than the default.  For
 244 example, to set @-H8m -K1m@:
 245
 246 <tscreen><verb>
 247 #include "rtsdefs.h"
 248 void defaultsHook (void) {
 249    RTSflags.GcFlags.stksSize =  1000002 / sizeof(W_);
 250    RTSflags.GcFlags.heapSize =  8000002 / sizeof(W_);
 251 }
 252 </verb></tscreen>
 253
 254 Don't use powers of two for heap/stack sizes: these are more likely to
 255 interact badly with direct-mapped caches.  The full set of flags is
 256 defined in @ghc/includes/RtsFlags.lh@ the the GHC source tree.
 257
 258 You can also change the messages printed when the runtime system
 259 ``blows up,'' e.g., on stack overflow.  The hooks for these are as
 260 follows:
 261
 262 <descrip>
 263 <tag>@void ErrorHdrHook (FILE *)@:</tag>
 264 <nidx>ErrorHdrHook</nidx>
 265 What's printed out before the message from @error@.
 266
 267 <tag>@void OutOfHeapHook (unsigned long, unsigned long)@:</tag>
 268 <nidx>OutOfHeapHook</nidx>
 269 The heap-overflow message.
 270
 271 <tag>@void StackOverflowHook (long int)@:</tag>
 272 <nidx>StackOverflowHook</nidx>
 273 The stack-overflow message.
 274
 275 <tag>@void MallocFailHook (long int)@:</tag>
 276 <nidx>MallocFailHook</nidx>
 277 The message printed if @malloc@ fails.
 278
 279 <tag>@void PatErrorHdrHook (FILE *)@:</tag>
 280 <nidx>PatErrorHdrHook</nidx>
 281 The message printed if a pattern-match fails (the failures
 282 that were not handled by the Haskell programmer).
 283
 284 <tag>@void PreTraceHook (FILE *)@:</tag>
 285 <nidx>PreTraceHook</nidx>
 286 What's printed out before a @trace@ message.
 287
 288 <tag>@void PostTraceHook (FILE *)@:</tag>
 289 <nidx>PostTraceHook</nidx>
 290 What's printed out after a @trace@ message.
 291 </descrip>
 292
 293 For example, here is the ``hooks'' code used by GHC itself:
 294 <tscreen><verb>
 295 #include <stdio.h>
 296 #define W_ unsigned long int
 297 #define I_ long int
 298
 299 void
 300 ErrorHdrHook (FILE *where)
 301 {
 302     fprintf(where, "\n"); /* no "Fail: " */
 303 }
 304
 305 void
 306 OutOfHeapHook (W_ request_size, W_ heap_size) /* both sizes in bytes */
 307 {
 308     fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
 309         allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
 310         option to increase the total heap size.\n",
 311         request_size,
 312         heap_size);
 313 }
 314
 315 void
 316 StackOverflowHook (I_ stack_size)    /* in bytes */
 317 {
 318     fprintf(stderr, "GHC stack-space overflow: current size
 319         %ld bytes.\nUse the `-K<size>' option to increase it.\n",
 320         stack_size);
 321 }
 322
 323 void
 324 PatErrorHdrHook (FILE *where)
 325 {
 326     fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
 327         This is a compiler bug; please report it to
 328         glasgow-haskell-bugs@dcs.gla.ac.uk.\n\nFail: ");
 329 }
 330
 331 void
 332 PreTraceHook (FILE *where)
 333 {
 334     fprintf(where, "\n"); /* not "Trace On" */
 335 }
 336
 337 void
 338 PostTraceHook (FILE *where)
 339 {
 340     fprintf(where, "\n"); /* not "Trace Off" */
 341 }
 342 </verb></tscreen>