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