Backtrace.hs

-- |
-- Module      :  Control.Exception.Backtrace
-- 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)
--
-- 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]
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- See module docstring above.


module Control.Exception.Backtrace
    ( -- * Backtrace mechanisms
      BacktraceMechanism(..)
    , getBacktraceMechanismState
    , setBacktraceMechanismState
      -- * Collecting backtraces
    , Backtraces
    , displayBacktraces
    , collectBacktraces
    ) where

import GHC.Internal.Exception.Backtrace