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