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