Copyright | (c) The University of Glasgow 1994-2023 |
---|---|
License | see libraries/base/LICENSE |
Maintainer | ghc-devs@haskell.org |
Stability | internal |
Portability | non-portable (GHC Extensions) |
Safe Haskell | None |
Language | Haskell2010 |
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 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 usinggetCurrentCCS
.HasCallStackBacktrace
captures theHasCallStack
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).
Synopsis
- data BacktraceMechanism
- getBacktraceMechanismState :: BacktraceMechanism -> IO Bool
- setBacktraceMechanismState :: BacktraceMechanism -> Bool -> IO ()
- data Backtraces
- displayBacktraces :: Backtraces -> String
- collectBacktraces :: (?callStack :: CallStack) => IO Backtraces
Backtrace mechanisms
data BacktraceMechanism Source #
How to collect a backtrace when an exception is thrown.
CostCentreBacktrace | collect cost-centre stack backtraces (only available when built with profiling) |
HasCallStackBacktrace | collect |
ExecutionBacktrace | collect backtraces via native execution stack unwinding (e.g. using DWARF debug information) |
IPEBacktrace | collect backtraces from Info Table Provenance Entries |
getBacktraceMechanismState :: BacktraceMechanism -> IO Bool Source #
Will the given BacktraceMechanism
be used when collecting
backtraces?
setBacktraceMechanismState :: BacktraceMechanism -> Bool -> IO () Source #
Set whether the given BacktraceMechanism
will be used when collecting
backtraces?
Collecting backtraces
displayBacktraces :: Backtraces -> String Source #
Render a set of backtraces to a human-readable string.
collectBacktraces :: (?callStack :: CallStack) => IO Backtraces Source #
Collect a set of Backtraces
.