Control.Exception.Backtrace

Description

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 using 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 CostCentreBacktraces are readily mapped back to the source program, they require that the program be instrumented with cost-centres, incurring runtime cost. Similarly, HasCallStackBacktraces require that the program be manually annotated with HasCallStack constraints.

By contrast, IPEBacktraces 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.

ExecutionBacktraces are similar to IPEBacktraces 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).