diff --git a/libraries/base/src/Control/Exception/Backtrace.hs b/libraries/base/src/Control/Exception/Backtrace.hs index 37c3fa9493ef3e039824a5044723f9286fc1c589..0b85bebe8932d4da84ee24063c3c26ad8c5ab338 100644 --- a/libraries/base/src/Control/Exception/Backtrace.hs +++ b/libraries/base/src/Control/Exception/Backtrace.hs @@ -7,8 +7,38 @@ -- Stability : internal -- Portability : non-portable (GHC Extensions) -- --- Mechanisms for collecting diagnostic backtraces and their representation. +-- This module provides the 'Backtrace'\ s type, which provides a +-- common representation for backtrace information which can be, e.g., attached +-- to exceptions (via the 'Control.Exception.Context.ExceptionContext' facility). +-- These backtraces preserve useful context about the execution state of the program +-- using a variety of means; we call these means *backtrace mechanisms*. -- +-- We currently support four backtrace mechanisms: +-- +-- - 'CostCentreBacktrace' captures the current cost-centre stack +-- using 'GHC.Stack.CCS.getCurrentCCS'. +-- - 'HasCallStackBacktrace' captures the 'HasCallStack' 'CallStack'. +-- - 'ExecutionBacktrace' captures the execution stack, unwound and resolved +-- to symbols via DWARF debug information. +-- - 'IPEBacktrace' captures the execution stack, resolved to names via info-table +-- provenance information. +-- +-- Each of these are useful in different situations. While 'CostCentreBacktrace's are +-- readily mapped back to the source program, they require that the program be instrumented +-- with cost-centres, incurring runtime cost. Similarly, 'HasCallStackBacktrace's require that +-- the program be manually annotated with 'HasCallStack' constraints. +-- +-- By contrast, 'IPEBacktrace's incur no runtime instrumentation but require that (at least +-- some subset of) the program be built with GHC\'s @-finfo-table-map@ flag. Moreover, because +-- info-table provenance information is derived after optimisation, it may be harder to relate +-- back to the structure of the source program. +-- +-- 'ExecutionBacktrace's are similar to 'IPEBacktrace's but use DWARF stack unwinding +-- and symbol resolution; this allows for useful backtraces even in the presence +-- of foreign calls, both into and out of Haskell. However, for robust stack unwinding +-- the entirety of the program (and its dependencies, both Haskell and native) must +-- be compiled with debugging information (e.g. using GHC\'s @-g@ flag). + -- Note [Backtrace mechanisms] -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/libraries/ghc-internal/src/GHC/Internal/Exception/Backtrace.hs b/libraries/ghc-internal/src/GHC/Internal/Exception/Backtrace.hs index e917987ebbab2fff6813383858b55f5a2337e174..ebfe748e5d6e1acdb50feac020f17e2efa5d0ca5 100644 --- a/libraries/ghc-internal/src/GHC/Internal/Exception/Backtrace.hs +++ b/libraries/ghc-internal/src/GHC/Internal/Exception/Backtrace.hs @@ -33,7 +33,7 @@ data BacktraceMechanism = CostCentreBacktrace -- | collect 'HasCallStack' backtraces | HasCallStackBacktrace - -- | collect backtraces from native execution stack unwinding + -- | collect backtraces via native execution stack unwinding (e.g. using DWARF debug information) | ExecutionBacktrace -- | collect backtraces from Info Table Provenance Entries | IPEBacktrace