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