content: -- |
  -- 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
  