diff options
Diffstat (limited to 'docs/users_guide/runtime_control.rst')
| -rw-r--r-- | docs/users_guide/runtime_control.rst | 79 |
1 files changed, 73 insertions, 6 deletions
diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst index 422eaa2ceb..0c38ac5919 100644 --- a/docs/users_guide/runtime_control.rst +++ b/docs/users_guide/runtime_control.rst @@ -117,8 +117,8 @@ Setting RTS options with the ``GHCRTS`` environment variable .. envvar:: GHCRTS - If the ``-rtsopts`` flag is set to something other than ``none`` when - linking, RTS options are also taken from the environment variable + If the ``-rtsopts`` flag is set to something other than ``none`` or ``ignoreAll`` + when linking, RTS options are also taken from the environment variable :envvar:`GHCRTS`. For example, to set the maximum heap size to 2G for all GHC-compiled programs (using an ``sh``\-like shell): @@ -218,7 +218,28 @@ Miscellaneous RTS options interval timer signal is still enabled. The timer signal is either SIGVTALRM or SIGALRM, depending on the RTS configuration and OS capabilities. To disable the timer signal, use the ``-V0`` RTS - option (see above). + option (see :rts-flag:`-V ⟨secs⟩`). + +.. rts-flag:: --install-seh-handlers=⟨yes|no⟩ + + If yes (the default), the RTS on Windows installs exception handlers to + catch unhandled exceptions using the Windows exception handling mechanism. + This option is primarily useful for when you are using the Haskell code as a + DLL, and don't want the RTS to ungracefully terminate your application on + erros such as segfaults. + +.. rts-flag:: --generate-crash-dumps + + If yes (the default), the RTS on Windows will generate a core dump on + any crash. These dumps can be inspected using debuggers such as WinDBG. + The dumps record all code, registers and threading information at the time + of the crash. Note that this implies `--install-seh-handlers=yes`. + +.. rts-flag:: --generate-stack-traces=<yes|no> + + If yes (the default), the RTS on Windows will generate a stack trace on + crashes if exception handling are enabled. In order to get more information + in compiled executables, C code or DLLs symbols need to be available. .. rts-flag:: -xm ⟨address⟩ @@ -514,7 +535,7 @@ performance. .. rts-flag:: -I ⟨seconds⟩ - :default: 0.3 seconds + :default: 0.3 seconds in the threaded runtime, 0 in the non-threaded runtime .. index:: single: idle GC @@ -664,7 +685,7 @@ performance. single: NUMA, enabling in the runtime Enable NUMA-aware memory allocation in the runtime (only available - with ``-threaded``, and only on Linux currently). + with ``-threaded``, and only on Linux and Windows currently). Background: some systems have a Non-Uniform Memory Architecture, whereby main memory is split into banks which are "local" to @@ -707,6 +728,44 @@ performance. that indicates the NUMA nodes on which to run the program. For example, ``--numa=3`` would run the program on NUMA nodes 0 and 1. +.. rts-flag:: --long-gc-sync + --long-gc-sync=<seconds> + + .. index:: + single: GC sync time, measuring + + When a GC starts, all the running mutator threads have to stop and + synchronise. The period between when the GC is initiated and all + the mutator threads are stopped is called the GC synchronisation + phase. If this phase is taking a long time (longer than 1ms is + considered long), then it can have a severe impact on overall + throughput. + + A long GC sync can be caused by a mutator thread that is inside an + ``unsafe`` FFI call, or running in a loop that doesn't allocate + memory and so doesn't yield. To fix the former, make the call + ``safe``, and to fix the latter, either avoid calling the code in + question or compile it with :ghc-flag:`-fomit-yields`. + + By default, the flag will cause a warning to be emitted to stderr + when the sync time exceeds the specified time. This behaviour can + be overriden, however: the ``longGCSync()`` hook is called when + the sync time is exceeded during the sync period, and the + ``longGCSyncEnd()`` hook at the end. Both of these hooks can be + overriden in the ``RtsConfig`` when the runtime is started with + ``hs_init_ghc()``. The default implementations of these hooks + (``LongGcSync()`` and ``LongGCSyncEnd()`` respectively) print + warnings to stderr. + + One way to use this flag is to set a breakpoint on + ``LongGCSync()`` in the debugger, and find the thread that is + delaying the sync. You probably want to use :ghc-flag:`-g` to + provide more info to the debugger. + + The GC sync time, along with other GC stats, are available by + calling the ``getRTSStats()`` function from C, or + ``GHC.Stats.getRTSStats`` from Haskell. + .. _rts-options-statistics: RTS options to produce runtime statistics @@ -717,6 +776,7 @@ RTS options to produce runtime statistics -s [⟨file⟩] -S [⟨file⟩] --machine-readable + --internal-counters These options produce runtime-system statistics, such as the amount of time spent executing the program and in the garbage collector, @@ -726,7 +786,10 @@ RTS options to produce runtime statistics line of output in the same format as GHC's ``-Rghc-timing`` option, ``-s`` produces a more detailed summary at the end of the program, and ``-S`` additionally produces information about each and every - garbage collection. + garbage collection. Passing ``--internal-counters`` to a threaded + runtime will cause a detailed summary to include various internal + counts accumulated during the run; note that these are unspecified + and may change between releases. The output is placed in ⟨file⟩. If ⟨file⟩ is omitted, then the output is sent to ``stderr``. @@ -1156,6 +1219,7 @@ Getting information about the RTS ,("Word size", "64") ,("Compiler unregisterised", "NO") ,("Tables next to code", "YES") + ,("Flag -with-rtsopts", "") ] The information is formatted such that it can be read as a of type @@ -1206,3 +1270,6 @@ Getting information about the RTS performance optimisation that is not available on all platforms. This field tells you whether the program has been compiled with this optimisation. (Usually yes, except on unusual platforms.) + + ``Flag -with-rtsopts`` + The value of the GHC flag :ghc-flag:`-with-rtsopts=⟨opts⟩` at compile/link time. |