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