ghc/docs/users_guide/runtime_control.sgml

   1 <sect1 id="runtime-control">
   2   <title>Running a compiled program</title>
   3
   4   <indexterm><primary>runtime control of Haskell programs</primary></indexterm>
   5   <indexterm><primary>running, compiled program</primary></indexterm>
   6   <indexterm><primary>RTS options</primary></indexterm>
   7
   8   <para>To make an executable program, the GHC system compiles your
   9   code and then links it with a non-trivial runtime system (RTS),
  10   which handles storage management, profiling, etc.</para>
  11
  12   <para>You have some control over the behaviour of the RTS, by giving
  13   special command-line arguments to your program.</para>
  14
  15   <para>When your Haskell program starts up, its RTS extracts
  16   command-line arguments bracketed between
  17   <option>+RTS</option><indexterm><primary><option>+RTS</option></primary></indexterm>
  18   and
  19   <option>-RTS</option><indexterm><primary><option>-RTS</option></primary></indexterm>
  20   as its own.  For example:</para>
  21
  22 <screen>
  23 % ./a.out -f +RTS -p -S -RTS -h foo bar
  24 </screen>
  25
  26   <para>The RTS will snaffle <option>-p</option> <option>-S</option>
  27   for itself, and the remaining arguments <literal>-f -h foo bar</literal>
  28   will be handed to your program if/when it calls
  29   <function>System.getArgs</function>.</para>
  30
  31   <para>No <option>-RTS</option> option is required if the
  32   runtime-system options extend to the end of the command line, as in
  33   this example:</para>
  34
  35 <screen>
  36 % hls -ltr /usr/etc +RTS -A5m
  37 </screen>
  38
  39   <para>If you absolutely positively want all the rest of the options
  40   in a command line to go to the program (and not the RTS), use a
  41   <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>.</para>
  42
  43   <para>As always, for RTS options that take
  44   <replaceable>size</replaceable>s: If the last character of
  45   <replaceable>size</replaceable> is a K or k, multiply by 1000; if an
  46   M or m, by 1,000,000; if a G or G, by 1,000,000,000.  (And any
  47   wraparound in the counters is <emphasis>your</emphasis>
  48   fault!)</para>
  49
  50   <para>Giving a <literal>+RTS -f</literal>
  51   <indexterm><primary><option>-f</option></primary><secondary>RTS option</secondary></indexterm> option
  52   will print out the RTS options actually available in your program
  53   (which vary, depending on how you compiled).</para>
  54
  55   <para>NOTE: since GHC is itself compiled by GHC, you can change RTS
  56   options in the compiler using the normal
  57   <literal>+RTS ... -RTS</literal>
  58   combination.  eg. to increase the maximum heap
  59   size for a compilation to 128M, you would add
  60   <literal>+RTS -M128m -RTS</literal>
  61   to the command line.</para>
  62
  63   <sect2 id="rts-options-gc">
  64     <title>RTS options to control the garbage-collector</title>
  65
  66     <indexterm><primary>RTS options, garbage-collection</primary></indexterm>
  67
  68     <para>There are several options to give you precise control over
  69     garbage collection.  Hopefully, you won't need any of these in
  70     normal operation, but there are several things that can be tweaked
  71     for maximum performance.</para>
  72
  73     <variablelist>
  74
  75       <varlistentry>
  76         <term><option>-A</option><replaceable>size</replaceable></Term>
  77         <indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm>
  78         <indexterm><primary>allocation area, size</primary></indexterm>
  79         <listitem>
  80           <para>&lsqb;Default: 256k&rsqb; Set the allocation area size
  81           used by the garbage collector.  The allocation area
  82           (actually generation 0 step 0) is fixed and is never resized
  83           (unless you use <option>-H</option>, below).</para>
  84
  85           <para>Increasing the allocation area size may or may not
  86           give better performance (a bigger allocation area means
  87           worse cache behaviour but fewer garbage collections and less
  88           promotion).</para>
  89
  90           <para>With only 1 generation (<option>-G1</option>) the
  91           <option>-A</option> option specifies the minimum allocation
  92           area, since the actual size of the allocation area will be
  93           resized according to the amount of data in the heap (see
  94           <option>-F</option>, below).</para>
  95         </listitem>
  96       </varlistentry>
  97
  98       <varlistentry>
  99         <term><option>-F</option><replaceable>factor</replaceable></Term>
 100         <listitem>
 101           <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>
 102           <indexterm><primary>heap size, factor</primary></indexterm>
 103
 104           <para>&lsqb;Default: 2&rsqb; This option controls the amount
 105           of memory reserved for the older generations (and in the
 106           case of a two space collector the size of the allocation
 107           area) as a factor of the amount of live data.  For example,
 108           if there was 2M of live data in the oldest generation when
 109           we last collected it, then by default we'll wait until it
 110           grows to 4M before collecting it again.</para>
 111
 112           <para>The default seems to work well here.  If you have
 113           plenty of memory, it is usually better to use
 114           <option>-H</option><replaceable>size</replaceable> than to
 115           increase
 116           <option>-F</option><replaceable>factor</replaceable>.</para>
 117
 118           <para>The <option>-F</option> setting will be automatically
 119           reduced by the garbage collector when the maximum heap size
 120           (the <option>-M</option><replaceable>size</replaceable>
 121           setting) is approaching.</para>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>-G</option><replaceable>generations</replaceable></Term>
 127         <indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm>
 128         <indexterm><primary>generations, number
 129         of</primary></indexterm>
 130         <listitem>
 131           <para>&lsqb;Default: 2&rsqb; Set the number of generations
 132           used by the garbage collector.  The default of 2 seems to be
 133           good, but the garbage collector can support any number of
 134           generations.  Anything larger than about 4 is probably not a
 135           good idea unless your program runs for a
 136           <emphasis>long</emphasis> time, because the oldest
 137           generation will hardly ever get collected.</para>
 138
 139           <para>Specifying 1 generation with <option>+RTS -G1</option>
 140           gives you a simple 2-space collector, as you would expect.
 141           In a 2-space collector, the <option>-A</option> option (see
 142           above) specifies the <Emphasis>minimum</Emphasis> allocation
 143           area size, since the allocation area will grow with the
 144           amount of live data in the heap.  In a multi-generational
 145           collector the allocation area is a fixed size (unless you
 146           use the <option>-H</option> option, see below).</para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <VarListEntry>
 151         <term><option>-H</option><replaceable>size</replaceable></term>
 152         <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
 153         <indexterm><primary>heap size, suggested</primary></indexterm>
 154         <listitem>
 155           <para>&lsqb;Default: 0&rsqb; This option provides a
 156           &ldquo;suggested heap size&rdquo; for the garbage collector.  The
 157           garbage collector will use about this much memory until the
 158           program residency grows and the heap size needs to be
 159           expanded to retain reasonable performance.</para>
 160
 161           <para>By default, the heap will start small, and grow and
 162           shrink as necessary.  This can be bad for performance, so if
 163           you have plenty of memory it's worthwhile supplying a big
 164           <option>-H</option><replaceable>size</replaceable>.  For
 165           improving GC performance, using
 166           <option>-H</option><replaceable>size</replaceable> is
 167           usually a better bet than
 168           <option>-A</option><replaceable>size</replaceable>.</para>
 169         </listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>-k</option><replaceable>size</replaceable></term>
 174         <indexterm><primary><option>-k</option></primary><secondary>RTS option</secondary></indexterm>
 175         <indexterm><primary>stack, minimum size</primary></indexterm>
 176         <listitem>
 177           <para>&lsqb;Default: 1k&rsqb; Set the initial stack size for
 178           new threads.  Thread stacks (including the main thread's
 179           stack) live on the heap, and grow as required.  The default
 180           value is good for concurrent applications with lots of small
 181           threads; if your program doesn't fit this model then
 182           increasing this option may help performance.</para>
 183
 184           <para>The main thread is normally started with a slightly
 185           larger heap to cut down on unnecessary stack growth while
 186           the program is starting up.</para>
 187         </listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>-K</option><replaceable>size</replaceable></term>
 192         <indexterm><primary><option>-K</option></primary><secondary>RTS option</secondary></indexterm>
 193         <indexterm><primary>stack, maximum size</primary></indexterm>
 194         <listitem>
 195           <para>&lsqb;Default: 1M&rsqb; Set the maximum stack size for
 196           an individual thread to <replaceable>size</replaceable>
 197           bytes.  This option is there purely to stop the program
 198           eating up all the available memory in the machine if it gets
 199           into an infinite loop.</para>
 200         </listitem>
 201       </varlistentry>
 202
 203       <varlistentry>
 204         <term><option>-m</option><replaceable>n</replaceable></term>
 205         <indexterm><primary><option>-m</option></primary><secondary>RTS option</secondary></indexterm>
 206         <indexterm><primary>heap, minimum free</primary></indexterm>
 207         <listitem>
 208           <para>Minimum &percnt; <replaceable>n</replaceable> of heap
 209           which must be available for allocation.  The default is
 210           3&percnt;.</para>
 211         </listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>-M</option><replaceable>size</replaceable></term>
 216         <indexterm><primary><option>-M</option></primary><secondary>RTS option</secondary></indexterm>
 217         <indexterm><primary>heap size, maximum</primary></indexterm>
 218         <listitem>
 219           <para>&lsqb;Default: 64M&rsqb; Set the maximum heap size to
 220           <replaceable>size</replaceable> bytes.  The heap normally
 221           grows and shrinks according to the memory requirements of
 222           the program.  The only reason for having this option is to
 223           stop the heap growing without bound and filling up all the
 224           available swap space, which at the least will result in the
 225           program being summarily killed by the operating
 226           system.</para>
 227         </listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><option>-s</option><replaceable>file</replaceable></term>
 232         <term><option>-S</option><replaceable>file</replaceable></Term>
 233         <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
 234         <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
 235         <listitem>
 236           <para>Write modest (<option>-s</option>) or verbose
 237           (<option>-S</option>) garbage-collector statistics into file
 238           <replaceable>file</replaceable>. The default
 239           <replaceable>file</replaceable> is
 240           <Filename><replaceable>program</replaceable>.stat</Filename>. The
 241           <replaceable>file</replaceable> <constant>stderr</constant>
 242           is treated specially, with the output really being sent to
 243           <constant>stderr</constant>.</para>
 244
 245           <para>This option is useful for watching how the storage
 246           manager adjusts the heap size based on the current amount of
 247           live data.</para>
 248         </listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term><option>-t</option></term>
 253         <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
 254         <listitem>
 255           <para>Write a one-line GC stats summary after running the
 256           program.  This output is in the same format as that produced
 257           by the <option>-Rghc-timing</option> option.</para>
 258         </listitem>
 259       </varlistentry>
 260     </variablelist>
 261
 262   </sect2>
 263
 264 <!-- ---------------------------------------------------------------------- -->
 265   <sect2>
 266     <title>RTS options for profiling and Concurrent/Parallel Haskell</title>
 267
 268     <para>The RTS options related to profiling are described in <XRef
 269     LinkEnd="prof-rts-options">; and those for concurrent/parallel
 270     stuff, in <XRef LinkEnd="parallel-rts-opts">.</para>
 271   </sect2>
 272
 273 <!-- ---------------------------------------------------------------------- -->
 274   <sect2>
 275     <title>RTS options for hackers, debuggers, and over-interested
 276     souls</title>
 277
 278     <indexterm><primary>RTS options, hacking/debugging</primary></indexterm>
 279
 280     <para>These RTS options might be used (a)&nbsp;to avoid a GHC bug,
 281     (b)&nbsp;to see &ldquo;what's really happening&rdquo;, or
 282     (c)&nbsp;because you feel like it.  Not recommended for everyday
 283     use!</para>
 284
 285     <variablelist>
 286
 287       <varlistentry>
 288         <term><option>-B</option></term>
 289         <indexterm><primary><option>-B</option></primary><secondary>RTS option</secondary></indexterm>
 290         <listitem>
 291           <para>Sound the bell at the start of each (major) garbage
 292           collection.</para>
 293
 294           <para>Oddly enough, people really do use this option!  Our
 295           pal in Durham (England), Paul Callaghan, writes: &ldquo;Some
 296           people here use it for a variety of
 297           purposes&mdash;honestly!&mdash;e.g., confirmation that the
 298           code/machine is doing something, infinite loop detection,
 299           gauging cost of recently added code. Certain people can even
 300           tell what stage &lsqb;the program&rsqb; is in by the beep
 301           pattern. But the major use is for annoying others in the
 302           same office&hellip;&rdquo;</para>
 303         </listitem>
 304       </varlistentry>
 305
 306       <varlistentry>
 307         <term><option>-r</option><replaceable>file</replaceable></term>
 308         <indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm>
 309         <indexterm><primary>ticky ticky profiling</primary></indexterm>
 310         <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm>
 311         <listitem>
 312           <para>Produce &ldquo;ticky-ticky&rdquo; statistics at the
 313           end of the program run.  The <replaceable>file</replaceable>
 314           business works just like on the <option>-S</option> RTS
 315           option (above).</para>
 316
 317           <para>&ldquo;Ticky-ticky&rdquo; statistics are counts of
 318           various program actions (updates, enters, etc.)  The program
 319           must have been compiled using
 320           <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
 321           (a.k.a. &ldquo;ticky-ticky profiling&rdquo;), and, for it to
 322           be really useful, linked with suitable system libraries.
 323           Not a trivial undertaking: consult the installation guide on
 324           how to set things up for easy &ldquo;ticky-ticky&rdquo;
 325           profiling.  For more information, see <XRef
 326           LinkEnd="ticky-ticky">.</para>
 327         </listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><option>-D</option><replaceable>num</replaceable></term>
 332         <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm>
 333         <listitem>
 334           <para>An RTS debugging flag; varying quantities of output
 335           depending on which bits are set in
 336           <replaceable>num</replaceable>.  Only works if the RTS was
 337           compiled with the <option>DEBUG</option> option.</para>
 338         </listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342         <term><option>-Z</option></term>
 343         <indexterm><primary><option>-Z</option></primary><secondary>RTS
 344         option</secondary></indexterm>
 345         <listitem>
 346           <para>Turn <emphasis>off</emphasis> &ldquo;update-frame
 347           squeezing&rdquo; at garbage-collection time.  (There's no
 348           particularly good reason to turn it off, except to ensure
 349           the accuracy of certain data collected regarding thunk entry
 350           counts.)</para>
 351         </listitem>
 352       </varlistentry>
 353     </variablelist>
 354
 355   </sect2>
 356
 357   <sect2 id="rts-hooks">
 358     <title>&ldquo;Hooks&rdquo; to change RTS behaviour</title>
 359
 360     <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
 361     <indexterm><primary>RTS hooks</primary></indexterm>
 362     <indexterm><primary>RTS behaviour, changing</primary></indexterm>
 363
 364     <para>GHC lets you exercise rudimentary control over the RTS
 365     settings for any given program, by compiling in a
 366     &ldquo;hook&rdquo; that is called by the run-time system.  The RTS
 367     contains stub definitions for all these hooks, but by writing your
 368     own version and linking it on the GHC command line, you can
 369     override the defaults.</para>
 370
 371     <para>Owing to the vagaries of DLL linking, these hooks don't work
 372     under Windows when the program is built dynamically.</para>
 373
 374     <para>The function
 375     <Function>defaultsHook</Function><indexterm><primary><function>defaultHook</function></primary></indexterm>
 376     lets you change various RTS options.  The commonest use for this
 377     is to give your program a default heap and/or stack size that is
 378     greater than the default.  For example, to set
 379     <literal>-M128m -K1m</literal>:</para>
 380
 381 <programlisting>
 382 #include "Rts.h"
 383 #include "RtsFlags.h"
 384 void defaultsHook (void) {
 385    RtsFlags.GcFlags.maxStkSize  =  1000002 / sizeof(W_);
 386    RtsFlags.GcFlags.maxHeapSize =  128*1024*1024 / BLOCK_SIZE_W;
 387 }
 388 </programlisting>
 389
 390     <para>Don't use powers of two for heap/stack sizes: these are more
 391     likely to interact badly with direct-mapped caches.  The full set
 392     of flags is defined in <Filename>ghc/rts/RtsFlags.h</Filename> the
 393     the GHC source tree.</para>
 394
 395     <para>You can also change the messages printed when the runtime
 396     system &ldquo;blows up,&rdquo; e.g., on stack overflow.  The hooks
 397     for these are as follows:</para>
 398
 399     <variablelist>
 400
 401       <varlistentry>
 402         <term><Function>void ErrorHdrHook (FILE *)</function></term>
 403         <indexterm><primary><function>ErrorHdrHook</function></primary></indexterm>
 404         <listitem>
 405           <para>What's printed out before the message from
 406           <function>error</function>.</para>
 407         </listitem>
 408       </varlistentry>
 409
 410       <varlistentry>
 411         <term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term>
 412         <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
 413         <ListItem>
 414           <para>The heap-overflow message.</para>
 415         </listitem>
 416       </varlistentry>
 417
 418       <varlistentry>
 419         <term><function>void StackOverflowHook (long int)</function></term>
 420         <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
 421         <listitem>
 422           <para>The stack-overflow message.</para>
 423         </listitem>
 424       </varlistentry>
 425
 426       <varlistentry>
 427         <term><function>void MallocFailHook (long int)</function></term>
 428         <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
 429         <listitem>
 430           <para>The message printed if <Function>malloc</Function>
 431           fails.</para>
 432         </listitem>
 433       </varlistentry>
 434
 435       <varlistentry>
 436         <term><function>void PatErrorHdrHook (FILE *)</function></term>
 437         <indexterm><primary><function>PatErrorHdrHook</function></primary></indexterm>
 438         <listitem>
 439           <para>The message printed if a pattern-match fails (the
 440           failures that were not handled by the Haskell
 441           programmer).</para>
 442         </listitem>
 443       </varlistentry>
 444
 445       <varlistentry>
 446         <term><function>void PreTraceHook (FILE *)</function></term>
 447         <indexterm><primary><function>PreTraceHook</function></primary></indexterm>
 448         <listitem>
 449           <para>What's printed out before a <Function>trace</Function>
 450           message.</para>
 451         </listitem>
 452       </varlistentry>
 453
 454       <varlistentry>
 455         <term><function>void PostTraceHook (FILE *)</function></term>
 456         <indexterm><primary><function>PostTraceHook</function></primary></indexterm>
 457         <listitem>
 458           <para>What's printed out after a <Function>trace</Function>
 459           message.</para>
 460         </listitem>
 461       </varlistentry>
 462     </variablelist>
 463
 464     <para>For example, here is the &ldquo;hooks&rdquo; code used by
 465     GHC itself:</para>
 466
 467 <programlisting>
 468 #include "Rts.h"
 469 #include "../rts/RtsFlags.h"
 470 #include "HsFFI.h"
 471
 472 void
 473 defaultsHook (void)
 474 {
 475     RtsFlags.GcFlags.heapSizeSuggestion = 6*1024*1024 / BLOCK_SIZE;
 476     RtsFlags.GcFlags.maxStkSize         = 8*1024*1024 / sizeof(W_);
 477     RtsFlags.GcFlags.giveStats = COLLECT_GC_STATS;
 478     RtsFlags.GcFlags.statsFile = stderr;
 479 }
 480
 481 void
 482 ErrorHdrHook (long fd)
 483 {
 484     char msg[]="\n";
 485     write(fd,msg,1);
 486 }
 487
 488 void
 489 PatErrorHdrHook (long fd)
 490 {
 491     const char msg[]="\n*** Pattern-matching error within GHC!\n\nThis is a compiler bug; please report it to glasgow-haskell-bugs@haskell.org.\n\nFail:";
 492     write(fd,msg,sizeof(msg)-1);
 493 }
 494
 495 void
 496 PreTraceHook (long fd)
 497 {
 498     const char msg[]="\n";
 499     write(fd,msg,sizeof(msg)-1);
 500 }
 501
 502 void
 503 PostTraceHook (long fd)
 504 {
 505 #if 0
 506     const char msg[]="\n";
 507     write(fd,msg,sizeof(msg)-1);
 508 #endif
 509 }
 510 </programlisting>
 511
 512   </sect2>
 513 </sect1>
 514
 515 <!-- Emacs stuff:
 516      ;;; Local Variables: ***
 517      ;;; mode: sgml ***
 518      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
 519      ;;; End: ***
 520  -->