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 id="rts-options-debugging">
 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>-D</option><replaceable>num</replaceable></term>
 308         <indexterm><primary>-D</primary><secondary>RTS option</secondary></indexterm>
 309         <listitem>
 310           <para>An RTS debugging flag; varying quantities of output
 311           depending on which bits are set in
 312           <replaceable>num</replaceable>.  Only works if the RTS was
 313           compiled with the <option>DEBUG</option> option.</para>
 314         </listitem>
 315       </varlistentry>
 316
 317       <varlistentry>
 318         <term><option>-r</option><replaceable>file</replaceable></term>
 319         <indexterm><primary><option>-r</option></primary><secondary>RTS option</secondary></indexterm>
 320         <indexterm><primary>ticky ticky profiling</primary></indexterm>
 321         <indexterm><primary>profiling</primary><secondary>ticky ticky</secondary></indexterm>
 322         <listitem>
 323           <para>Produce &ldquo;ticky-ticky&rdquo; statistics at the
 324           end of the program run.  The <replaceable>file</replaceable>
 325           business works just like on the <option>-S</option> RTS
 326           option (above).</para>
 327
 328           <para>&ldquo;Ticky-ticky&rdquo; statistics are counts of
 329           various program actions (updates, enters, etc.)  The program
 330           must have been compiled using
 331           <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
 332           (a.k.a. &ldquo;ticky-ticky profiling&rdquo;), and, for it to
 333           be really useful, linked with suitable system libraries.
 334           Not a trivial undertaking: consult the installation guide on
 335           how to set things up for easy &ldquo;ticky-ticky&rdquo;
 336           profiling.  For more information, see <XRef
 337           LinkEnd="ticky-ticky">.</para>
 338         </listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342         <term><option>-xc</option></term>
 343         <indexterm><primary><option>-xc</option></primary><secondary>RTS
 344         option</secondary></indexterm>
 345         <listitem>
 346           <para>(Only available when the program is compiled for
 347           profiling.)  When an exception is raised in the program,
 348           this option causes the current cost-centre-stack to be
 349           dumped to <literal>stderr</literal>.</para>
 350
 351           <para>This can be particularly useful for debugging: if your
 352           program is complaining about a <literal>head []</literal>
 353           error and you haven't got a clue which bit of code is
 354           causing it, compiling with <literal>-prof
 355           -auto-all</literal> and running with <literal>+RTS -xc
 356           -RTS</literal> will tell you exactly the call stack at the
 357           point the error was raised.</para>
 358         </listitem>
 359       </varlistentry>
 360
 361       <varlistentry>
 362         <term><option>-Z</option></term>
 363         <indexterm><primary><option>-Z</option></primary><secondary>RTS
 364         option</secondary></indexterm>
 365         <listitem>
 366           <para>Turn <emphasis>off</emphasis> &ldquo;update-frame
 367           squeezing&rdquo; at garbage-collection time.  (There's no
 368           particularly good reason to turn it off, except to ensure
 369           the accuracy of certain data collected regarding thunk entry
 370           counts.)</para>
 371         </listitem>
 372       </varlistentry>
 373     </variablelist>
 374
 375   </sect2>
 376
 377   <sect2 id="rts-hooks">
 378     <title>&ldquo;Hooks&rdquo; to change RTS behaviour</title>
 379
 380     <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
 381     <indexterm><primary>RTS hooks</primary></indexterm>
 382     <indexterm><primary>RTS behaviour, changing</primary></indexterm>
 383
 384     <para>GHC lets you exercise rudimentary control over the RTS
 385     settings for any given program, by compiling in a
 386     &ldquo;hook&rdquo; that is called by the run-time system.  The RTS
 387     contains stub definitions for all these hooks, but by writing your
 388     own version and linking it on the GHC command line, you can
 389     override the defaults.</para>
 390
 391     <para>Owing to the vagaries of DLL linking, these hooks don't work
 392     under Windows when the program is built dynamically.</para>
 393
 394     <para>The function
 395     <Function>defaultsHook</Function><indexterm><primary><function>defaultHook</function></primary></indexterm>
 396     lets you change various RTS options.  The commonest use for this
 397     is to give your program a default heap and/or stack size that is
 398     greater than the default.  For example, to set
 399     <literal>-M128m -K1m</literal>:</para>
 400
 401 <programlisting>
 402 #include "Rts.h"
 403 #include "RtsFlags.h"
 404 void defaultsHook (void) {
 405    RtsFlags.GcFlags.maxStkSize  =  1000002 / sizeof(W_);
 406    RtsFlags.GcFlags.maxHeapSize =  128*1024*1024 / BLOCK_SIZE_W;
 407 }
 408 </programlisting>
 409
 410     <para>Don't use powers of two for heap/stack sizes: these are more
 411     likely to interact badly with direct-mapped caches.  The full set
 412     of flags is defined in <Filename>ghc/rts/RtsFlags.h</Filename> the
 413     the GHC source tree.</para>
 414
 415     <para>You can also change the messages printed when the runtime
 416     system &ldquo;blows up,&rdquo; e.g., on stack overflow.  The hooks
 417     for these are as follows:</para>
 418
 419     <variablelist>
 420
 421       <varlistentry>
 422         <term><Function>void ErrorHdrHook (FILE *)</function></term>
 423         <indexterm><primary><function>ErrorHdrHook</function></primary></indexterm>
 424         <listitem>
 425           <para>What's printed out before the message from
 426           <function>error</function>.</para>
 427         </listitem>
 428       </varlistentry>
 429
 430       <varlistentry>
 431         <term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term>
 432         <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
 433         <ListItem>
 434           <para>The heap-overflow message.</para>
 435         </listitem>
 436       </varlistentry>
 437
 438       <varlistentry>
 439         <term><function>void StackOverflowHook (long int)</function></term>
 440         <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
 441         <listitem>
 442           <para>The stack-overflow message.</para>
 443         </listitem>
 444       </varlistentry>
 445
 446       <varlistentry>
 447         <term><function>void MallocFailHook (long int)</function></term>
 448         <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
 449         <listitem>
 450           <para>The message printed if <Function>malloc</Function>
 451           fails.</para>
 452         </listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><function>void PatErrorHdrHook (FILE *)</function></term>
 457         <indexterm><primary><function>PatErrorHdrHook</function></primary></indexterm>
 458         <listitem>
 459           <para>The message printed if a pattern-match fails (the
 460           failures that were not handled by the Haskell
 461           programmer).</para>
 462         </listitem>
 463       </varlistentry>
 464
 465       <varlistentry>
 466         <term><function>void PreTraceHook (FILE *)</function></term>
 467         <indexterm><primary><function>PreTraceHook</function></primary></indexterm>
 468         <listitem>
 469           <para>What's printed out before a <Function>trace</Function>
 470           message.</para>
 471         </listitem>
 472       </varlistentry>
 473
 474       <varlistentry>
 475         <term><function>void PostTraceHook (FILE *)</function></term>
 476         <indexterm><primary><function>PostTraceHook</function></primary></indexterm>
 477         <listitem>
 478           <para>What's printed out after a <Function>trace</Function>
 479           message.</para>
 480         </listitem>
 481       </varlistentry>
 482     </variablelist>
 483
 484     <para>For example, here is the &ldquo;hooks&rdquo; code used by
 485     GHC itself:</para>
 486
 487 <programlisting>
 488 #include "Rts.h"
 489 #include "../rts/RtsFlags.h"
 490 #include "HsFFI.h"
 491
 492 void
 493 defaultsHook (void)
 494 {
 495     RtsFlags.GcFlags.heapSizeSuggestion = 6*1024*1024 / BLOCK_SIZE;
 496     RtsFlags.GcFlags.maxStkSize         = 8*1024*1024 / sizeof(W_);
 497     RtsFlags.GcFlags.giveStats = COLLECT_GC_STATS;
 498     RtsFlags.GcFlags.statsFile = stderr;
 499 }
 500
 501 void
 502 ErrorHdrHook (long fd)
 503 {
 504     char msg[]="\n";
 505     write(fd,msg,1);
 506 }
 507
 508 void
 509 PatErrorHdrHook (long fd)
 510 {
 511     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:";
 512     write(fd,msg,sizeof(msg)-1);
 513 }
 514
 515 void
 516 PreTraceHook (long fd)
 517 {
 518     const char msg[]="\n";
 519     write(fd,msg,sizeof(msg)-1);
 520 }
 521
 522 void
 523 PostTraceHook (long fd)
 524 {
 525 #if 0
 526     const char msg[]="\n";
 527     write(fd,msg,sizeof(msg)-1);
 528 #endif
 529 }
 530 </programlisting>
 531
 532   </sect2>
 533 </sect1>
 534
 535 <!-- Emacs stuff:
 536      ;;; Local Variables: ***
 537      ;;; mode: sgml ***
 538      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
 539      ;;; End: ***
 540  -->