Move user's guide to ReStructuredText
[ghc.git] / docs / users_guide / runtime_control.rst
1 .. _runtime-control:
2
3 Running a compiled program
4 ==========================
5
6 .. index::
7    single: runtime control of Haskell programs
8    single: running, compiled program
9    single: RTS options
10
11 To make an executable program, the GHC system compiles your code and
12 then links it with a non-trivial runtime system (RTS), which handles
13 storage management, thread scheduling, profiling, and so on.
14
15 The RTS has a lot of options to control its behaviour. For example, you
16 can change the context-switch interval, the default size of the heap,
17 and enable heap profiling. These options can be passed to the runtime
18 system in a variety of different ways; the next section
19 (:ref:`setting-rts-options`) describes the various methods, and the
20 following sections describe the RTS options themselves.
21
22 .. _setting-rts-options:
23
24 Setting RTS options
25 -------------------
26
27 .. index::
28    single: RTS options, setting
29
30 There are four ways to set RTS options:
31
32 -  on the command line between ``+RTS ... -RTS``, when running the
33    program (:ref:`rts-opts-cmdline`)
34
35 -  at compile-time, using ``--with-rtsopts``
36    (:ref:`rts-opts-compile-time`)
37
38 -  with the environment variable ``GHCRTS``
39    (:ref:`rts-options-environment`)
40
41 -  by overriding "hooks" in the runtime system (:ref:`rts-hooks`)
42
43 .. _rts-opts-cmdline:
44
45 Setting RTS options on the command line
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47
48 .. index::
49    single: +RTS
50    single: -RTS
51    single: --RTS
52
53 If you set the ``-rtsopts`` flag appropriately when linking (see
54 :ref:`options-linker`), you can give RTS options on the command line
55 when running your program.
56
57 When your Haskell program starts up, the RTS extracts command-line
58 arguments bracketed between ``+RTS`` and ``-RTS`` as its own. For example:
59
60 ::
61
62     $ ghc prog.hs -rtsopts
63     [1 of 1] Compiling Main             ( prog.hs, prog.o )
64     Linking prog ...
65     $ ./prog -f +RTS -H32m -S -RTS -h foo bar
66
67 The RTS will snaffle ``-H32m -S`` for itself, and the remaining
68 arguments ``-f -h foo bar`` will be available to your program if/when it
69 calls ``System.Environment.getArgs``.
70
71 No ``-RTS`` option is required if the runtime-system options extend to
72 the end of the command line, as in this example:
73
74 ::
75
76     % hls -ltr /usr/etc +RTS -A5m
77
78 If you absolutely positively want all the rest of the options in a
79 command line to go to the program (and not the RTS), use a
80 ``--RTS``.
81
82 As always, for RTS options that take ⟨size⟩s: If the last character of
83 ⟨size⟩ is a K or k, multiply by 1000; if an M or m, by 1,000,000; if a G
84 or G, by 1,000,000,000. (And any wraparound in the counters is *your*
85 fault!)
86
87 Giving a ``+RTS -?`` ``-?``\ RTS option option will print out the RTS
88 options actually available in your program (which vary, depending on how
89 you compiled).
90
91 .. note::
92     Since GHC is itself compiled by GHC, you can change RTS options in
93     the compiler using the normal ``+RTS ... -RTS`` combination. For instance, to set
94     the maximum heap size for a compilation to 128M, you would add
95     ``+RTS -M128m -RTS`` to the command line.
96
97 .. _rts-opts-compile-time:
98
99 Setting RTS options at compile time
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101
102 GHC lets you change the default RTS options for a program at compile
103 time, using the ``-with-rtsopts`` flag (:ref:`options-linker`). A common
104 use for this is to give your program a default heap and/or stack size
105 that is greater than the default. For example, to set ``-H128m -K64m``,
106 link with ``-with-rtsopts="-H128m -K64m"``.
107
108 .. _rts-options-environment:
109
110 Setting RTS options with the ``GHCRTS`` environment variable
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113 .. index::
114    single: RTS options; from the environment
115    single: environment variable; for setting RTS options
116    single: GHCRTS environment variable
117
118 If the ``-rtsopts`` flag is set to something other than ``none`` when
119 linking, RTS options are also taken from the environment variable
120 ``GHCRTS``. For example, to set the maximum heap size to 2G
121 for all GHC-compiled programs (using an ``sh``\-like shell):
122
123 ::
124
125     GHCRTS='-M2G'
126     export GHCRTS
127
128 RTS options taken from the ``GHCRTS`` environment variable can be
129 overridden by options given on the command line.
130
131 .. tip::
132     Setting something like ``GHCRTS=-M2G`` in your environment is a
133     handy way to avoid Haskell programs growing beyond the real memory in
134     your machine, which is easy to do by accident and can cause the machine
135     to slow to a crawl until the OS decides to kill the process (and you
136     hope it kills the right one).
137
138 .. _rts-hooks:
139
140 "Hooks" to change RTS behaviour
141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142
143 .. index::
144    single: hooks; RTS
145    single: RTS hooks
146    single: RTS behaviour, changing
147
148 GHC lets you exercise rudimentary control over certain RTS settings for
149 any given program, by compiling in a "hook" that is called by the
150 run-time system. The RTS contains stub definitions for these hooks, but
151 by writing your own version and linking it on the GHC command line, you
152 can override the defaults.
153
154 Owing to the vagaries of DLL linking, these hooks don't work under
155 Windows when the program is built dynamically.
156
157 You can change the messages printed when the runtime system "blows up,"
158 e.g., on stack overflow. The hooks for these are as follows:
159
160 ``void OutOfHeapHook (unsigned long, unsigned long)``
161     .. index::
162        single: OutOfHeapHook
163
164     The heap-overflow message.
165
166 ``void StackOverflowHook (long int)``
167     .. index::
168        single: StackOverflowHook
169
170     The stack-overflow message.
171
172 ``void MallocFailHook (long int)``
173     .. index::
174        single: MallocFailHook
175
176     The message printed if ``malloc`` fails.
177
178 .. _rts-options-misc:
179
180 Miscellaneous RTS options
181 -------------------------
182
183 ``-Vsecs``
184     .. index::
185        single: -V; RTS option
186
187     Sets the interval that the RTS clock ticks at. The runtime uses a
188     single timer signal to count ticks; this timer signal is used to
189     control the context switch timer (:ref:`using-concurrent`) and the
190     heap profiling timer :ref:`rts-options-heap-prof`. Also, the time
191     profiler uses the RTS timer signal directly to record time profiling
192     samples.
193
194     Normally, setting the ``-V`` option directly is not necessary: the
195     resolution of the RTS timer is adjusted automatically if a short
196     interval is requested with the ``-C`` or ``-i`` options. However,
197     setting ``-V`` is required in order to increase the resolution of
198     the time profiler.
199
200     Using a value of zero disables the RTS clock completely, and has the
201     effect of disabling timers that depend on it: the context switch
202     timer and the heap profiling timer. Context switches will still
203     happen, but deterministically and at a rate much faster than normal.
204     Disabling the interval timer is useful for debugging, because it
205     eliminates a source of non-determinism at runtime.
206
207 ``--install-signal-handlers=yes|no``
208     .. index::
209        single: --install-signal-handlers; RTS option
210
211     If yes (the default), the RTS installs signal handlers to catch
212     things like ctrl-C. This option is primarily useful for when you are
213     using the Haskell code as a DLL, and want to set your own signal
214     handlers.
215
216     Note that even with ``--install-signal-handlers=no``, the RTS
217     interval timer signal is still enabled. The timer signal is either
218     SIGVTALRM or SIGALRM, depending on the RTS configuration and OS
219     capabilities. To disable the timer signal, use the ``-V0`` RTS
220     option (see above).
221
222 ``-xmaddress``
223     .. index::
224        single: -xm; RTS option
225
226     WARNING: this option is for working around memory allocation
227     problems only. Do not use unless GHCi fails with a message like
228     “\ ``failed to mmap() memory below 2Gb``\ ”. If you need to use this
229     option to get GHCi working on your machine, please file a bug.
230
231     On 64-bit machines, the RTS needs to allocate memory in the low 2Gb
232     of the address space. Support for this across different operating
233     systems is patchy, and sometimes fails. This option is there to give
234     the RTS a hint about where it should be able to allocate memory in
235     the low 2Gb of the address space. For example,
236     ``+RTS -xm20000000 -RTS`` would hint that the RTS should allocate
237     starting at the 0.5Gb mark. The default is to use the OS's built-in
238     support for allocating memory in the low 2Gb if available (e.g.
239     ``mmap`` with ``MAP_32BIT`` on Linux), or otherwise ``-xm40000000``.
240
241 ``-xqsize``
242     .. index::
243        single: -xq; RTS option
244
245     [Default: 100k] This option relates to allocation limits; for more
246     about this see
247     :base-ref:`enableAllocationLimit <GHC-Conc.html#v%3AenableAllocationLimit>`.
248     When a thread hits its allocation limit, the RTS throws an exception
249     to the thread, and the thread gets an additional quota of allocation
250     before the exception is raised again, the idea being so that the
251     thread can execute its exception handlers. The ``-xq`` controls the
252     size of this additional quota.
253
254 .. _rts-options-gc:
255
256 RTS options to control the garbage collector
257 --------------------------------------------
258
259 .. index::
260    single: garbage collector; options
261    single: RTS options; garbage collection
262
263 There are several options to give you precise control over garbage
264 collection. Hopefully, you won't need any of these in normal operation,
265 but there are several things that can be tweaked for maximum
266 performance.
267
268 ``-A ⟨size⟩``
269     .. index::
270        single: -A; RTS option
271        single: allocation area, size
272
273     [Default: 512k] Set the allocation area size used by the garbage
274     collector. The allocation area (actually generation 0 step 0) is
275     fixed and is never resized (unless you use ``-H``, below).
276
277     Increasing the allocation area size may or may not give better
278     performance (a bigger allocation area means worse cache behaviour
279     but fewer garbage collections and less promotion).
280
281     With only 1 generation (``-G1``) the ``-A`` option specifies the
282     minimum allocation area, since the actual size of the allocation
283     area will be resized according to the amount of data in the heap
284     (see ``-F``, below).
285
286 ``-O ⟨size⟩``
287     .. index::
288        single: -O; RTS option
289        single: old generation, size
290
291     [Default: 1m] Set the minimum size of the old generation. The old
292     generation is collected whenever it grows to this size or the value
293     of the ``-F`` option multiplied by the size of the live data at the
294     previous major collection, whichever is larger.
295
296 ``-n ⟨size⟩``
297     .. index::
298        single: -n; RTS option
299
300     .. index::
301        single: allocation area, chunk size
302
303     [Default: 0, Example: ``-n4m``\ ] When set to a non-zero value, this
304     option divides the allocation area (``-A`` value) into chunks of the
305     specified size. During execution, when a processor exhausts its
306     current chunk, it is given another chunk from the pool until the
307     pool is exhausted, at which point a collection is triggered.
308
309     This option is only useful when running in parallel (``-N2`` or
310     greater). It allows the processor cores to make better use of the
311     available allocation area, even when cores are allocating at
312     different rates. Without ``-n``, each core gets a fixed-size
313     allocation area specified by the ``-A``, and the first core to
314     exhaust its allocation area triggers a GC across all the cores. This
315     can result in a collection happening when the allocation areas of
316     some cores are only partially full, so the purpose of the ``-n`` is
317     to allow cores that are allocating faster to get more of the
318     allocation area. This means less frequent GC, leading a lower GC
319     overhead for the same heap size.
320
321     This is particularly useful in conjunction with larger ``-A``
322     values, for example ``-A64m -n4m`` is a useful combination on larger core
323     counts (8+).
324
325 ``-c``
326     .. index::
327        single: -c; RTS option
328
329     .. index::
330        single: garbage collection; compacting
331
332     .. index::
333        single: compacting garbage collection
334
335     Use a compacting algorithm for collecting the oldest generation. By
336     default, the oldest generation is collected using a copying
337     algorithm; this option causes it to be compacted in-place instead.
338     The compaction algorithm is slower than the copying algorithm, but
339     the savings in memory use can be considerable.
340
341     For a given heap size (using the ``-H`` option), compaction can in
342     fact reduce the GC cost by allowing fewer GCs to be performed. This
343     is more likely when the ratio of live data to heap size is high, say
344     greater than 30%.
345
346     .. note::
347        Compaction doesn't currently work when a single generation is
348        requested using the ``-G1`` option.
349
350 ``-c ⟨n⟩``
351     [Default: 30] Automatically enable compacting collection when the
352     live data exceeds ⟨n⟩% of the maximum heap size (see the ``-M``
353     option). Note that the maximum heap size is unlimited by default, so
354     this option has no effect unless the maximum heap size is set with
355     ``-M ⟨size⟩.``
356
357 ``-F ⟨factor⟩``
358     .. index::
359        single: -F; RTS option
360        single: heap size, factor
361
362     [Default: 2] This option controls the amount of memory reserved for
363     the older generations (and in the case of a two space collector the
364     size of the allocation area) as a factor of the amount of live data.
365     For example, if there was 2M of live data in the oldest generation
366     when we last collected it, then by default we'll wait until it grows
367     to 4M before collecting it again.
368
369     The default seems to work well here. If you have plenty of memory,
370     it is usually better to use ``-H ⟨size⟩`` than to increase
371     ``-F ⟨factor⟩.``
372
373     The ``-F`` setting will be automatically reduced by the garbage
374     collector when the maximum heap size (the ``-M ⟨size⟩`` setting) is
375     approaching.
376
377 ``-G ⟨generations⟩``
378     .. index::
379        single: -G; RTS option
380        single: generations, number of
381
382     [Default: 2] Set the number of generations used by the garbage
383     collector. The default of 2 seems to be good, but the garbage
384     collector can support any number of generations. Anything larger
385     than about 4 is probably not a good idea unless your program runs
386     for a *long* time, because the oldest generation will hardly ever
387     get collected.
388
389     Specifying 1 generation with ``+RTS -G1`` gives you a simple 2-space
390     collector, as you would expect. In a 2-space collector, the ``-A``
391     option (see above) specifies the *minimum* allocation area size,
392     since the allocation area will grow with the amount of live data in
393     the heap. In a multi-generational collector the allocation area is a
394     fixed size (unless you use the ``-H`` option, see below).
395
396 ``-qggen``
397     .. index::
398        single: -qg; RTS option
399
400     [New in GHC 6.12.1] [Default: 0] Use parallel GC in generation ⟨gen⟩
401     and higher. Omitting ⟨gen⟩ turns off the parallel GC completely,
402     reverting to sequential GC.
403
404     The default parallel GC settings are usually suitable for parallel
405     programs (i.e. those using ``par``, Strategies, or with multiple
406     threads). However, it is sometimes beneficial to enable the parallel
407     GC for a single-threaded sequential program too, especially if the
408     program has a large amount of heap data and GC is a significant
409     fraction of runtime. To use the parallel GC in a sequential program,
410     enable the parallel runtime with a suitable ``-N`` option, and
411     additionally it might be beneficial to restrict parallel GC to the
412     old generation with ``-qg1``.
413
414 ``-qbgen``
415     .. index::
416        single: -qb; RTS option
417
418     [New in GHC 6.12.1] [Default: 1] Use load-balancing in the parallel
419     GC in generation ⟨gen⟩ and higher. Omitting ⟨gen⟩ disables
420     load-balancing entirely.
421
422     Load-balancing shares out the work of GC between the available
423     cores. This is a good idea when the heap is large and we need to
424     parallelise the GC work, however it is also pessimal for the short
425     young-generation collections in a parallel program, because it can
426     harm locality by moving data from the cache of the CPU where is it
427     being used to the cache of another CPU. Hence the default is to do
428     load-balancing only in the old-generation. In fact, for a parallel
429     program it is sometimes beneficial to disable load-balancing
430     entirely with ``-qb``.
431
432 ``-H [⟨size⟩]``
433     .. index::
434        single: -H; RTS option
435        single: heap size, suggested
436
437     [Default: 0] This option provides a “suggested heap size” for the
438     garbage collector. Think of ``-Hsize`` as a variable ``-A`` option.
439     It says: I want to use at least ⟨size⟩ bytes, so use whatever is
440     left over to increase the ``-A`` value.
441
442     This option does not put a *limit* on the heap size: the heap may
443     grow beyond the given size as usual.
444
445     If ⟨size⟩ is omitted, then the garbage collector will take the size
446     of the heap at the previous GC as the ⟨size⟩. This has the effect of
447     allowing for a larger ``-A`` value but without increasing the
448     overall memory requirements of the program. It can be useful when
449     the default small ``-A`` value is suboptimal, as it can be in
450     programs that create large amounts of long-lived data.
451
452 ``-I ⟨seconds⟩``
453     .. index::
454        single: -I; RTS option
455        single: idle GC
456
457     (default: 0.3) In the threaded and SMP versions of the RTS (see
458     ``-threaded``, :ref:`options-linker`), a major GC is automatically
459     performed if the runtime has been idle (no Haskell computation has
460     been running) for a period of time. The amount of idle time which
461     must pass before a GC is performed is set by the ``-I ⟨seconds⟩``
462     option. Specifying ``-I0`` disables the idle GC.
463
464     For an interactive application, it is probably a good idea to use
465     the idle GC, because this will allow finalizers to run and
466     deadlocked threads to be detected in the idle time when no Haskell
467     computation is happening. Also, it will mean that a GC is less
468     likely to happen when the application is busy, and so responsiveness
469     may be improved. However, if the amount of live data in the heap is
470     particularly large, then the idle GC can cause a significant delay,
471     and too small an interval could adversely affect interactive
472     responsiveness.
473
474     This is an experimental feature, please let us know if it causes
475     problems and/or could benefit from further tuning.
476
477 ``-ki ⟨size⟩``
478     .. index::
479        single: -k; RTS option
480        single: stack, initial size
481
482     [Default: 1k] Set the initial stack size for new threads.
483
484     Thread stacks (including the main thread's stack) live on the heap.
485     As the stack grows, new stack chunks are added as required; if the
486     stack shrinks again, these extra stack chunks are reclaimed by the
487     garbage collector. The default initial stack size is deliberately
488     small, in order to keep the time and space overhead for thread
489     creation to a minimum, and to make it practical to spawn threads for
490     even tiny pieces of work.
491
492     .. note::
493         This flag used to be simply ``-k``, but was renamed to ``-ki`` in
494         GHC 7.2.1. The old name is still accepted for backwards
495         compatibility, but that may be removed in a future version.
496
497 ``-kc ⟨size⟩``
498     .. index::
499        single: -kc; RTS option
500        single: stack; chunk size
501
502     [Default: 32k] Set the size of “stack chunks”. When a thread's
503     current stack overflows, a new stack chunk is created and added to
504     the thread's stack, until the limit set by ``-K`` is reached.
505
506     The advantage of smaller stack chunks is that the garbage collector
507     can avoid traversing stack chunks if they are known to be unmodified
508     since the last collection, so reducing the chunk size means that the
509     garbage collector can identify more stack as unmodified, and the GC
510     overhead might be reduced. On the other hand, making stack chunks
511     too small adds some overhead as there will be more
512     overflow/underflow between chunks. The default setting of 32k
513     appears to be a reasonable compromise in most cases.
514
515 ``-kb ⟨size⟩``
516     .. index::
517        single: -kc; RTS option
518        single: stack; chunk buffer size
519
520     [Default: 1k] Sets the stack chunk buffer size. When a stack chunk
521     overflows and a new stack chunk is created, some of the data from
522     the previous stack chunk is moved into the new chunk, to avoid an
523     immediate underflow and repeated overflow/underflow at the boundary.
524     The amount of stack moved is set by the ``-kb`` option.
525
526     Note that to avoid wasting space, this value should typically be
527     less than 10% of the size of a stack chunk (``-kc``), because in a
528     chain of stack chunks, each chunk will have a gap of unused space of
529     this size.
530
531 ``-K ⟨size⟩``
532     .. index::
533        single: -K; RTS option
534        single: stack, maximum size
535
536     [Default: 80% physical memory size] Set the maximum stack size for
537     an individual thread to ⟨size⟩ bytes. If the thread attempts to
538     exceed this limit, it will be sent the ``StackOverflow`` exception.
539     The limit can be disabled entirely by specifying a size of zero.
540
541     This option is there mainly to stop the program eating up all the
542     available memory in the machine if it gets into an infinite loop.
543
544 ``-m ⟨n⟩``
545     .. index::
546        single: -m; RTS option
547        single: heap, minimum free
548
549     Minimum % ⟨n⟩ of heap which must be available for allocation. The
550     default is 3%.
551
552 ``-M ⟨size⟩``
553     .. index::
554        single: -M; RTS option
555        single: heap size, maximum
556
557     [Default: unlimited] Set the maximum heap size to ⟨size⟩ bytes. The
558     heap normally grows and shrinks according to the memory requirements
559     of the program. The only reason for having this option is to stop
560     the heap growing without bound and filling up all the available swap
561     space, which at the least will result in the program being summarily
562     killed by the operating system.
563
564     The maximum heap size also affects other garbage collection
565     parameters: when the amount of live data in the heap exceeds a
566     certain fraction of the maximum heap size, compacting collection
567     will be automatically enabled for the oldest generation, and the
568     ``-F`` parameter will be reduced in order to avoid exceeding the
569     maximum heap size.
570
571 .. _rts-options-statistics:
572
573 RTS options to produce runtime statistics
574 -----------------------------------------
575
576 ``-T``, ``-t [⟨file⟩]``, ``-s [⟨file⟩]``, ``-S [⟨file⟩]``, ``--machine-readable``
577     .. index::
578        single: -T; RTS option
579        single: -t; RTS option
580        single: -s; RTS option
581        single: -S; RTS option
582        single: --machine-readable; RTS option
583
584     These options produce runtime-system statistics, such as the amount
585     of time spent executing the program and in the garbage collector,
586     the amount of memory allocated, the maximum size of the heap, and so
587     on. The three variants give different levels of detail: ``-T``
588     collects the data but produces no output ``-t`` produces a single
589     line of output in the same format as GHC's ``-Rghc-timing`` option,
590     ``-s`` produces a more detailed summary at the end of the program,
591     and ``-S`` additionally produces information about each and every
592     garbage collection.
593
594     The output is placed in ⟨file⟩. If ⟨file⟩ is omitted, then the
595     output is sent to ``stderr``.
596
597     If you use the ``-T`` flag then, you should access the statistics
598     using :base-ref:`GHC.Stats <GHC-Stats.html>`.
599
600     If you use the ``-t`` flag then, when your program finishes, you
601     will see something like this:
602
603     ::
604
605         <<ghc: 36169392 bytes, 69 GCs, 603392/1065272 avg/max bytes residency (2 samples), 3M in use, 0.00 INIT (0.00 elapsed), 0.02 MUT (0.02 elapsed), 0.07 GC (0.07 elapsed) :ghc>>
606
607     This tells you:
608
609     -  The total number of bytes allocated by the program over the whole
610        run.
611
612     -  The total number of garbage collections performed.
613
614     -  The average and maximum "residency", which is the amount of live
615        data in bytes. The runtime can only determine the amount of live
616        data during a major GC, which is why the number of samples
617        corresponds to the number of major GCs (and is usually relatively
618        small). To get a better picture of the heap profile of your
619        program, use the ``-hT`` RTS option (:ref:`rts-profiling`).
620
621     -  The peak memory the RTS has allocated from the OS.
622
623     -  The amount of CPU time and elapsed wall clock time while
624        initialising the runtime system (INIT), running the program
625        itself (MUT, the mutator), and garbage collecting (GC).
626
627     You can also get this in a more future-proof, machine readable
628     format, with ``-t --machine-readable``:
629
630     ::
631
632          [("bytes allocated", "36169392")
633          ,("num_GCs", "69")
634          ,("average_bytes_used", "603392")
635          ,("max_bytes_used", "1065272")
636          ,("num_byte_usage_samples", "2")
637          ,("peak_megabytes_allocated", "3")
638          ,("init_cpu_seconds", "0.00")
639          ,("init_wall_seconds", "0.00")
640          ,("mutator_cpu_seconds", "0.02")
641          ,("mutator_wall_seconds", "0.02")
642          ,("GC_cpu_seconds", "0.07")
643          ,("GC_wall_seconds", "0.07")
644          ]
645
646     If you use the ``-s`` flag then, when your program finishes, you
647     will see something like this (the exact details will vary depending
648     on what sort of RTS you have, e.g. you will only see profiling data
649     if your RTS is compiled for profiling):
650
651     ::
652
653               36,169,392 bytes allocated in the heap
654                4,057,632 bytes copied during GC
655                1,065,272 bytes maximum residency (2 sample(s))
656                   54,312 bytes maximum slop
657                        3 MB total memory in use (0 MB lost due to fragmentation)
658
659           Generation 0:    67 collections,     0 parallel,  0.04s,  0.03s elapsed
660           Generation 1:     2 collections,     0 parallel,  0.03s,  0.04s elapsed
661
662           SPARKS: 359207 (557 converted, 149591 pruned)
663
664           INIT  time    0.00s  (  0.00s elapsed)
665           MUT   time    0.01s  (  0.02s elapsed)
666           GC    time    0.07s  (  0.07s elapsed)
667           EXIT  time    0.00s  (  0.00s elapsed)
668           Total time    0.08s  (  0.09s elapsed)
669
670           %GC time      89.5%  (75.3% elapsed)
671
672           Alloc rate    4,520,608,923 bytes per MUT second
673
674           Productivity  10.5% of total user, 9.1% of total elapsed
675
676     -  The "bytes allocated in the heap" is the total bytes allocated by
677        the program over the whole run.
678
679     -  GHC uses a copying garbage collector by default. "bytes copied
680        during GC" tells you how many bytes it had to copy during garbage
681        collection.
682
683     -  The maximum space actually used by your program is the "bytes
684        maximum residency" figure. This is only checked during major
685        garbage collections, so it is only an approximation; the number
686        of samples tells you how many times it is checked.
687
688     -  The "bytes maximum slop" tells you the most space that is ever
689        wasted due to the way GHC allocates memory in blocks. Slop is
690        memory at the end of a block that was wasted. There's no way to
691        control this; we just like to see how much memory is being lost
692        this way.
693
694     -  The "total memory in use" tells you the peak memory the RTS has
695        allocated from the OS.
696
697     -  Next there is information about the garbage collections done. For
698        each generation it says how many garbage collections were done,
699        how many of those collections were done in parallel, the total
700        CPU time used for garbage collecting that generation, and the
701        total wall clock time elapsed while garbage collecting that
702        generation.
703
704     -  The ``SPARKS`` statistic refers to the use of
705        ``Control.Parallel.par`` and related functionality in the
706        program. Each spark represents a call to ``par``; a spark is
707        "converted" when it is executed in parallel; and a spark is
708        "pruned" when it is found to be already evaluated and is
709        discarded from the pool by the garbage collector. Any remaining
710        sparks are discarded at the end of execution, so "converted" plus
711        "pruned" does not necessarily add up to the total.
712
713     -  Next there is the CPU time and wall clock time elapsed broken
714        down by what the runtime system was doing at the time. INIT is
715        the runtime system initialisation. MUT is the mutator time, i.e.
716        the time spent actually running your code. GC is the time spent
717        doing garbage collection. RP is the time spent doing retainer
718        profiling. PROF is the time spent doing other profiling. EXIT is
719        the runtime system shutdown time. And finally, Total is, of
720        course, the total.
721
722        %GC time tells you what percentage GC is of Total. "Alloc rate"
723        tells you the "bytes allocated in the heap" divided by the MUT
724        CPU time. "Productivity" tells you what percentage of the Total
725        CPU and wall clock elapsed times are spent in the mutator (MUT).
726
727     The ``-S`` flag, as well as giving the same output as the ``-s``
728     flag, prints information about each GC as it happens:
729
730     ::
731
732             Alloc    Copied     Live    GC    GC     TOT     TOT  Page Flts
733             bytes     bytes     bytes  user  elap    user    elap
734            528496     47728    141512  0.01  0.02    0.02    0.02    0    0  (Gen:  1)
735         [...]
736            524944    175944   1726384  0.00  0.00    0.08    0.11    0    0  (Gen:  0)
737
738     For each garbage collection, we print:
739
740     -  How many bytes we allocated this garbage collection.
741
742     -  How many bytes we copied this garbage collection.
743
744     -  How many bytes are currently live.
745
746     -  How long this garbage collection took (CPU time and elapsed wall
747        clock time).
748
749     -  How long the program has been running (CPU time and elapsed wall
750        clock time).
751
752     -  How many page faults occurred this garbage collection.
753
754     -  How many page faults occurred since the end of the last garbage
755        collection.
756
757     -  Which generation is being garbage collected.
758
759 RTS options for concurrency and parallelism
760 -------------------------------------------
761
762 The RTS options related to concurrency are described in
763 :ref:`using-concurrent`, and those for parallelism in
764 :ref:`parallel-options`.
765
766 .. _rts-profiling:
767
768 RTS options for profiling
769 -------------------------
770
771 Most profiling runtime options are only available when you compile your
772 program for profiling (see :ref:`prof-compiler-options`, and
773 :ref:`rts-options-heap-prof` for the runtime options). However, there is
774 one profiling option that is available for ordinary non-profiled
775 executables:
776
777 ``-hT``
778     .. index::
779        single: -hT; RTS option
780
781     (can be shortened to ``-h``.) Generates a basic heap profile, in the
782     file ``prog.hp``. To produce the heap profile graph, use ``hp2ps``
783     (see :ref:`hp2ps`). The basic heap profile is broken down by data
784     constructor, with other types of closures (functions, thunks, etc.)
785     grouped into broad categories (e.g. ``FUN``, ``THUNK``). To get a
786     more detailed profile, use the full profiling support
787     (:ref:`profiling`).
788
789 .. _rts-eventlog:
790
791 Tracing
792 -------
793
794 .. index::
795    single: tracing
796    single: events
797    single: eventlog files
798
799 When the program is linked with the ``-eventlog`` option
800 (:ref:`options-linker`), runtime events can be logged in two ways:
801
802 -  In binary format to a file for later analysis by a variety of tools.
803    One such tool is
804    `ThreadScope <http://www.haskell.org/haskellwiki/ThreadScope>`__\ ThreadScope,
805    which interprets the event log to produce a visual parallel execution
806    profile of the program.
807
808 -  As text to standard output, for debugging purposes.
809
810 ``-lflags``
811     .. index::
812        single: -l; RTS option
813
814     Log events in binary format to the file ``program.eventlog``.
815     Without any ⟨flags⟩ specified, this logs a default set of events,
816     suitable for use with tools like ThreadScope.
817
818     For some special use cases you may want more control over which
819     events are included. The ⟨flags⟩ is a sequence of zero or more
820     characters indicating which classes of events to log. Currently
821     these the classes of events that can be enabled/disabled:
822
823     - ``s`` — scheduler events, including Haskell thread creation and start/stop
824       events. Enabled by default.
825
826     - ``g`` — GC events, including GC start/stop. Enabled by default.
827
828     - ``p`` — parallel sparks (sampled). Enabled by default.
829
830     - ``f`` — parallel sparks (fully accurate). Disabled by default.
831
832     - ``u`` — user events. These are events emitted from Haskell code using
833       functions such as ``Debug.Trace.traceEvent``. Enabled by default.
834
835     You can disable specific classes, or enable/disable all classes at
836     once:
837
838     - ``a`` — enable all event classes listed above
839     - ``-⟨x⟩`` — disable the given class of events, for any event class listed above
840     - ``-a`` — disable all classes
841
842     For example, ``-l-ag`` would disable all event classes (``-a``) except for
843     GC events (``g``).
844
845     For spark events there are two modes: sampled and fully accurate.
846     There are various events in the life cycle of each spark, usually
847     just creating and running, but there are some more exceptional
848     possibilities. In the sampled mode the number of occurrences of each
849     kind of spark event is sampled at frequent intervals. In the fully
850     accurate mode every spark event is logged individually. The latter
851     has a higher runtime overhead and is not enabled by default.
852
853     The format of the log file is described by the header
854     ``EventLogFormat.h`` that comes with GHC, and it can be parsed in
855     Haskell using the
856     `ghc-events <http://hackage.haskell.org/package/ghc-events>`__
857     library. To dump the contents of a ``.eventlog`` file as text, use
858     the tool ``ghc-events show`` that comes with the
859     `ghc-events <http://hackage.haskell.org/package/ghc-events>`__
860     package.
861
862 ``-v [⟨flags⟩]``
863     .. index::
864        single: -v; RTS option
865
866     Log events as text to standard output, instead of to the
867     ``.eventlog`` file. The ⟨flags⟩ are the same as for ``-l``, with the
868     additional option ``t`` which indicates that the each event printed
869     should be preceded by a timestamp value (in the binary ``.eventlog``
870     file, all events are automatically associated with a timestamp).
871
872 The debugging options ``-Dx`` also generate events which are logged
873 using the tracing framework. By default those events are dumped as text
874 to stdout (``-Dx`` implies ``-v``), but they may instead be stored in
875 the binary eventlog file by using the ``-l`` option.
876
877 .. _rts-options-debugging:
878
879 RTS options for hackers, debuggers, and over-interested souls
880 -------------------------------------------------------------
881
882 .. index::
883    single: RTS options, hacking/debugging
884
885 These RTS options might be used (a) to avoid a GHC bug, (b) to see
886 "what's really happening", or (c) because you feel like it. Not
887 recommended for everyday use!
888
889 ``-B``
890     .. index::
891        single: -B; RTS option
892
893     Sound the bell at the start of each (major) garbage collection.
894
895     Oddly enough, people really do use this option! Our pal in Durham
896     (England), Paul Callaghan, writes: “Some people here use it for a
897     variety of purposes—honestly!—e.g., confirmation that the
898     code/machine is doing something, infinite loop detection, gauging
899     cost of recently added code. Certain people can even tell what stage
900     [the program] is in by the beep pattern. But the major use is for
901     annoying others in the same office…”
902
903 ``-D ⟨x⟩``
904     .. index::
905        single: -D; RTS option
906
907     An RTS debugging flag; only available if the program was linked with
908     the ``-debug`` option. Various values of ⟨x⟩ are provided to enable
909     debug messages and additional runtime sanity checks in different
910     subsystems in the RTS, for example ``+RTS -Ds -RTS`` enables debug
911     messages from the scheduler. Use ``+RTS -?`` to find out which debug
912     flags are supported.
913
914     Debug messages will be sent to the binary event log file instead of
915     stdout if the ``-l`` option is added. This might be useful for
916     reducing the overhead of debug tracing.
917
918 ``-r ⟨file⟩``
919     .. index::
920        single: -r; RTS option
921        single: ticky ticky profiling
922        single: profiling; ticky ticky
923
924     Produce "ticky-ticky" statistics at the end of the program run (only
925     available if the program was linked with ``-debug``). The ⟨file⟩
926     business works just like on the ``-S`` RTS option, above.
927
928     For more information on ticky-ticky profiling, see
929     :ref:`ticky-ticky`.
930
931 ``-xc``
932     .. index::
933        single: -xc; RTS option
934
935     (Only available when the program is compiled for profiling.) When an
936     exception is raised in the program, this option causes a stack trace
937     to be dumped to ``stderr``.
938
939     This can be particularly useful for debugging: if your program is
940     complaining about a ``head []`` error and you haven't got a clue
941     which bit of code is causing it, compiling with
942     ``-prof -fprof-auto`` and running with ``+RTS -xc -RTS`` will tell
943     you exactly the call stack at the point the error was raised.
944
945     The output contains one report for each exception raised in the
946     program (the program might raise and catch several exceptions during
947     its execution), where each report looks something like this:
948
949     ::
950
951         *** Exception raised (reporting due to +RTS -xc), stack trace:
952           GHC.List.CAF
953           --> evaluated by: Main.polynomial.table_search,
954           called from Main.polynomial.theta_index,
955           called from Main.polynomial,
956           called from Main.zonal_pressure,
957           called from Main.make_pressure.p,
958           called from Main.make_pressure,
959           called from Main.compute_initial_state.p,
960           called from Main.compute_initial_state,
961           called from Main.CAF
962           ...
963
964     The stack trace may often begin with something uninformative like
965     ``GHC.List.CAF``; this is an artifact of GHC's optimiser, which
966     lifts out exceptions to the top-level where the profiling system
967     assigns them to the cost centre "CAF". However, ``+RTS -xc`` doesn't
968     just print the current stack, it looks deeper and reports the stack
969     at the time the CAF was evaluated, and it may report further stacks
970     until a non-CAF stack is found. In the example above, the next stack
971     (after ``--> evaluated by``) contains plenty of information about
972     what the program was doing when it evaluated ``head []``.
973
974     Implementation details aside, the function names in the stack should
975     hopefully give you enough clues to track down the bug.
976
977     See also the function ``traceStack`` in the module ``Debug.Trace``
978     for another way to view call stacks.
979
980 ``-Z``
981     .. index::
982        single: -Z; RTS option
983
984     Turn *off* "update-frame squeezing" at garbage-collection time.
985     (There's no particularly good reason to turn it off, except to
986     ensure the accuracy of certain data collected regarding thunk entry
987     counts.)
988
989 .. _ghc-info:
990
991 Getting information about the RTS
992 ---------------------------------
993
994 .. index::
995    single: RTS
996
997 It is possible to ask the RTS to give some information about itself. To
998 do this, use the ``--info`` flag, e.g.
999
1000 ::
1001
1002     $ ./a.out +RTS --info
1003      [("GHC RTS", "YES")
1004      ,("GHC version", "6.7")
1005      ,("RTS way", "rts_p")
1006      ,("Host platform", "x86_64-unknown-linux")
1007      ,("Host architecture", "x86_64")
1008      ,("Host OS", "linux")
1009      ,("Host vendor", "unknown")
1010      ,("Build platform", "x86_64-unknown-linux")
1011      ,("Build architecture", "x86_64")
1012      ,("Build OS", "linux")
1013      ,("Build vendor", "unknown")
1014      ,("Target platform", "x86_64-unknown-linux")
1015      ,("Target architecture", "x86_64")
1016      ,("Target OS", "linux")
1017      ,("Target vendor", "unknown")
1018      ,("Word size", "64")
1019      ,("Compiler unregisterised", "NO")
1020      ,("Tables next to code", "YES")
1021      ]
1022
1023 The information is formatted such that it can be read as a of type
1024 ``[(String, String)]``. Currently the following fields are present:
1025
1026 ``GHC RTS``
1027     Is this program linked against the GHC RTS? (always "YES").
1028
1029 ``GHC version``
1030     The version of GHC used to compile this program.
1031
1032 ``RTS way``
1033     The variant (“way”) of the runtime. The most common values are
1034     ``rts_v`` (vanilla), ``rts_thr`` (threaded runtime, i.e. linked
1035     using the ``-threaded`` option) and ``rts_p`` (profiling runtime,
1036     i.e. linked using the ``-prof`` option). Other variants include
1037     ``debug`` (linked using ``-debug``), and ``dyn`` (the RTS is linked
1038     in dynamically, i.e. a shared library, rather than statically linked
1039     into the executable itself). These can be combined, e.g. you might
1040     have ``rts_thr_debug_p``.
1041
1042 ``Target platform``\ ``Target architecture``\ ``Target OS``\ ``Target vendor``
1043     These are the platform the program is compiled to run on.
1044
1045 ``Build platform``\ ``Build architecture``\ ``Build OS``\ ``Build vendor``
1046     These are the platform where the program was built on. (That is, the
1047     target platform of GHC itself.) Ordinarily this is identical to the
1048     target platform. (It could potentially be different if
1049     cross-compiling.)
1050
1051 ``Host platform``\ ``Host architecture``\ ``Host OS``\ ``Host vendor``
1052     These are the platform where GHC itself was compiled. Again, this
1053     would normally be identical to the build and target platforms.
1054
1055 ``Word size``
1056     Either ``"32"`` or ``"64"``, reflecting the word size of the target
1057     platform.
1058
1059 ``Compiler unregistered``
1060     Was this program compiled with an :ref:`"unregistered" <unreg>`
1061     version of GHC? (I.e., a version of GHC that has no
1062     platform-specific optimisations compiled in, usually because this is
1063     a currently unsupported platform.) This value will usually be no,
1064     unless you're using an experimental build of GHC.
1065
1066 ``Tables next to code``
1067     Putting info tables directly next to entry code is a useful
1068     performance optimisation that is not available on all platforms.
1069     This field tells you whether the program has been compiled with this
1070     optimisation. (Usually yes, except on unusual platforms.)