-- |-- 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.moduleControl.Exception.Backtrace (-- * Backtrace mechanismsBacktraceMechanism (..),getBacktraceMechanismState ,setBacktraceMechanismState -- * Collecting backtraces,Backtraces ,displayBacktraces ,collectBacktraces )whereimportGHC.Internal.Exception.Backtrace