base-4.21.0.0: Core data structures and operations
Copyright(c) The University of Glasgow 1994-2023
Licensesee libraries/base/LICENSE
Maintainerghc-devs@haskell.org
Stabilityinternal
Portabilitynon-portable (GHC Extensions)
Safe HaskellNone
LanguageHaskell2010

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:

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).

Synopsis

Backtrace mechanisms

data BacktraceMechanism Source #

How to collect a backtrace when an exception is thrown.

Constructors

CostCentreBacktrace

collect cost-centre stack backtraces (only available when built with profiling)

HasCallStackBacktrace

collect HasCallStack backtraces

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

data Backtraces Source #

A collection of 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.