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 -p -S -RTS -h foo bar
  25 \end{verbatim}
  26 The RTS will snaffle \tr{-p -S} for itself,
  27 and the remaining arguments \tr{-f -h foo bar} will be handed
  28 to your program when it does a @GetArgs@ I/O request.
  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 The amount of heap allocation will typically increase as the total heap
  87 size is reduced.  The reason for this odd behaviour is that updates of
  88 promoted-to-old-generation objects may require the extra allocation of a new-generation
  89 object to ensure that there are never any pointers from the old
  90 generation to the new generation.
  91
  92 For some garbage collectors (not including the default one, sadly),
  93 you can convert the \tr{-S} output into a residency graph (in
  94 PostScript), using the \tr{stat2resid}\index{stat2resid} utility in
  95 the GHC distribution (\tr{ghc/utils/stat2resid}).
  96
  97 \item[\tr{-N}:]
  98 \index{-N RTS option}
  99 Normally, the garbage collector black-holes closures which are being
 100 evaluated, as a space-saving measure.  That's exactly what you want
 101 for ordinary Haskell programs.
 102
 103 When signal handlers are present, however, a computation may be
 104 abandoned prematurely, leaving black holes behind.  If the signal
 105 handler shares one of these black-holed closures, disaster can result.
 106 Use the \tr{-N} option to prevent black-holing by the garbage
 107 collector if you suspect that your signal handlers may share {\em any}
 108 subexpressions with the top-level computation.  Expect your heap usage
 109 to increase, since the lifetimes of some closures may be extended.
 110 \end{description}
 111
 112 %************************************************************************
 113 %*                                                                      *
 114 \subsection{RTS options to control the garbage-collector}
 115 \index{RTS options, garbage-collection}
 116 %*                                                                      *
 117 %************************************************************************
 118
 119 Besides the \tr{-H} (set heap size) and \tr{-S}/\tr{-s} (GC stats) RTS
 120 options, there are several options to give you precise control over
 121 garbage collection.
 122
 123 \begin{description}
 124 \item[\tr{-M<n>}:]
 125 \index{-M<n> RTS option}
 126 Minimum \% \pl{<n>} of heap which must be available for allocation.
 127 The default is 3\%.
 128
 129 \item[\tr{-A<size>}:]
 130 \index{-A<size> RTS option}
 131 Sets a limit on the size of the allocation area for generational
 132 garbage collection to \pl{<size>} bytes (\tr{-A} gives default of 64k). If
 133 a negative size is given the size of the allocation is fixed to
 134 -\pl{<size>}. For non-generational collectors, it fixes the minimum
 135 heap which must be available after a collection, overriding the
 136 \tr{-M<n>} RTS option.
 137
 138 \item[\tr{-G<size>}:]
 139 \index{-G<size> RTS option}
 140 Sets the percentage of free space to be promoted before a major
 141 collection is invoked to \pl{<size>}\%. The default is 66\%. If a
 142 negative size is given it fixes the size of major generation threshold
 143 to -\pl{<size>} bytes.
 144
 145 \item[\tr{-F2s}:]
 146 \index{-F2s RTS option}
 147 Forces a program compiled for generational GC to use two-space copying
 148 collection. The two-space collector may outperform the generational
 149 collector for programs which have a very low heap residency. It can
 150 also be used to generate a statistics file from which a basic heap
 151 residency profile can be produced (see Section \ref{stat2resid}).
 152
 153 There will still be a small execution overhead imposed by the
 154 generational compilation as the test for old generation updates will
 155 still be executed (of course none will actually happen).  This
 156 overhead is typically less than 1\%.
 157
 158 \item[\tr{-j<size>}:]
 159 \index{-j<size> RTS option}
 160 Force a major garbage collection every \pl{<size>} bytes.  (Normally
 161 used because you're keen on getting major-GC stats, notably heap residency
 162 info.)
 163 \end{description}
 164
 165 %************************************************************************
 166 %*                                                                      *
 167 \subsection{RTS options for profiling and Concurrent/Parallel Haskell}
 168 %*                                                                      *
 169 %************************************************************************
 170
 171 The RTS options related to profiling are described in
 172 \Sectionref{prof-rts-options};
 173 and those for concurrent/parallel stuff, in \Sectionref{parallel-rts-opts}.
 174
 175 %************************************************************************
 176 %*                                                                      *
 177 \subsection{RTS options for hackers, debuggers, and over-interested souls}
 178 \index{RTS options, hacking/debugging}
 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 \begin{description}
 187 \item[\tr{-B}:]
 188 \index{-B RTS option}
 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), PaulCallaghan, 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 \item[\tr{-I}:]
 200 Use the ``debugging mini-interpreter'' with sanity-checking; you have
 201 to have an appropriately-compiled version of the prelude, etc.
 202 Goes together nicely with GDB (GNU debugger)...
 203 (OLD, REALLY)
 204
 205 \item[\tr{-r<file>}:]
 206 \index{-r <file> RTS option}
 207 Produce ``ticky-ticky'' statistics at the end of the program run.
 208 The \tr{<file>} business works just like on the \tr{-S} RTS option (above).
 209
 210 ``Ticky-ticky'' statistics are counts of various program actions
 211 (updates, enters, etc.)
 212 The program must have been compiled using
 213 \tr{-fstg-reduction-counts}\index{-fstg-reduction-counts option}
 214 (a.k.a. ``ticky-ticky profiling''), and, for it to be really useful,
 215 linked with suitable system libraries.  Not a trivial undertaking:
 216 consult the installation guide on how to set things up for
 217 easy ``ticky-ticky'' profiling.
 218
 219 \item[\tr{-T<num>}:]
 220 \index{-T RTS option}
 221 An RTS debugging flag; varying quantities of output depending on which bits
 222 are set in \pl{<num>}.
 223
 224 \item[\tr{-Z}:]
 225 \index{-Z RTS option}
 226 Turn {\em off} ``update-frame squeezing'' at garbage-collection time.
 227 (There's no particularly good reason to turn it off.)
 228 \end{description}
 229
 230 %************************************************************************
 231 %*                                                                      *
 232 \subsection[rts-hooks]{``Hooks'' to change RTS failure messages}
 233 \index{hooks, RTS}
 234 \index{RTS hooks}
 235 %*                                                                      *
 236 %************************************************************************
 237
 238 GHC lets you exercise rudimentary control over the messages printed
 239 when the runtime system ``blows up,'' e.g., on stack overflow.
 240
 241 Simply write some of the following procedures in C and then make sure
 242 they get linked in, in preference to those in the RTS library:
 243 \begin{description}
 244 \item[\tr{void ErrorHdrHook (FILE *)}:]
 245 \index{ErrorHdrHook}
 246 What's printed out before the message from \tr{error}.
 247
 248 \item[\tr{void OutOfHeapHook (unsigned long, unsigned long)}:]
 249 \index{OutOfHeapHook}
 250 The heap-overflow message.
 251
 252 \item[\tr{void StackOverflowHook (long int)}:]
 253 \index{StackOverflowHook}
 254 The stack-overflow message.
 255
 256 \item[\tr{void MallocFailHook (long int)}:]
 257 \index{MallocFailHook}
 258 The message printed if \tr{malloc} fails.
 259
 260 \item[\tr{void PatErrorHdrHook (FILE *)}:]
 261 \index{PatErrorHdrHook}
 262 The message printed if a pattern-match fails (the failures
 263 that were not handled by the Haskell programmer).
 264
 265 \item[\tr{void PreTraceHook (FILE *)}:]
 266 \index{PreTraceHook}
 267 What's printed out before a \tr{trace} message.
 268
 269 \item[\tr{void PostTraceHook (FILE *)}:]
 270 \index{PostTraceHook}
 271 What's printed out after a \tr{trace} message.
 272 \end{description}
 273
 274 For example, here is the ``hooks'' code used by GHC itself:
 275 \begin{verbatim}
 276 #include <stdio.h>
 277 #define W_ unsigned long int
 278 #define I_ long int
 279
 280 void
 281 ErrorHdrHook (where)
 282   FILE *where;
 283 {
 284     fprintf(where, "\n"); /* no "Fail: " */
 285 }
 286
 287 void
 288 OutOfHeapHook (request_size, heap_size)
 289   W_ request_size; /* in bytes */
 290   W_ heap_size;    /* in bytes */
 291 {
 292     fprintf(stderr, "GHC's heap exhausted;\nwhile trying to
 293         allocate %lu bytes in a %lu-byte heap;\nuse the `-H<size>'
 294         option to increase the total heap size.\n",
 295         request_size,
 296         heap_size);
 297 }
 298
 299 void
 300 StackOverflowHook (stack_size)
 301   I_ stack_size;    /* in bytes */
 302 {
 303     fprintf(stderr, "GHC stack-space overflow: current size
 304         %ld bytes.\nUse the `-K<size>' option to increase it.\n",
 305         stack_size);
 306 }
 307
 308 void
 309 PatErrorHdrHook (where)
 310   FILE *where;
 311 {
 312     fprintf(where, "\n*** Pattern-matching error within GHC!\n\n
 313         This is a compiler bug; please report it to
 314         glasgow-haskell-bugs@dcs.glasgow.ac.uk.\n\nFail: ");
 315 }
 316
 317 void
 318 PreTraceHook (where)
 319   FILE *where;
 320 {
 321     fprintf(where, "\n"); /* not "Trace On" */
 322 }
 323
 324 void
 325 PostTraceHook (where)
 326   FILE *where;
 327 {
 328     fprintf(where, "\n"); /* not "Trace Off" */
 329 }
 330 \end{verbatim}
 331
 332 %************************************************************************
 333 %*                                                                      *
 334 %\subsection[rts-control-shell-scripts]{Hiding the runtime-control mess with a shell script}
 335 %*                                                                      *
 336 %************************************************************************
 337
 338 %NOT DONE YET.
 339