ghc/docs/users_guide/runtime_control.lit

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