base-4.18.1.0: Basic libraries

Safe Haskell | None
Language | Haskell2010

GHC.Stack.CloneStack

Description

This module exposes an interface for capturing the state of a thread's execution stack for diagnostics purposes: `cloneMyStack`, `cloneThreadStack`.

Such a "cloned" stack can be decoded with `decode` to a stack trace, given that the `-finfo-table-map` is enabled.

Since: base-4.17.0.0

Synopsis

- data StackSnapshot = StackSnapshot !StackSnapshot#
- data StackEntry = StackEntry {
  - functionName :: String
  - moduleName :: String
  - srcLoc :: String
  - closureType :: Word
  }
- cloneMyStack :: IO StackSnapshot
- cloneThreadStack :: ThreadId -> IO StackSnapshot
- decode :: StackSnapshot -> IO [StackEntry]

# Documentation

data StackSnapshot Source #

A frozen snapshot of the state of an execution stack.

Since: base-4.17.0.0

Constructors

StackSnapshot !StackSnapshot# |

data StackEntry Source #

Representation for the source location where a return frame was pushed on the stack. This happens every time when a `case ... of` scrutinee is evaluated.

Constructors

StackEntry |

Fields

- functionName :: String
- moduleName :: String
- srcLoc :: String
- closureType :: Word

#### Instances

Instances details

Show StackEntry Source # |
Instance details Defined in GHC.Stack.CloneStack Methods showsPrec :: Int -> StackEntry -> ShowS Source # show :: StackEntry -> String Source # showList :: [StackEntry] -> ShowS Source #
Eq StackEntry Source # |
Instance details Defined in GHC.Stack.CloneStack Methods (==) :: StackEntry -> StackEntry -> Bool Source # (/=) :: StackEntry -> StackEntry -> Bool Source #

cloneMyStack :: IO StackSnapshot Source #

Clone the stack of the executing thread

Since: base-4.17.0.0

cloneThreadStack :: ThreadId -> IO StackSnapshot Source #

Clone the stack of a thread identified by its `ThreadId`

Since: base-4.17.0.0

decode :: StackSnapshot -> IO [StackEntry] Source #

Decode a `StackSnapshot` to a stacktrace (a list of `StackEntry`). The stack trace is created from return frames with according `InfoProvEnt` entries. To generate them, use the GHC flag `-finfo-table-map`. If there are no `InfoProvEnt` entries, an empty list is returned.

Please note:

- To gather `StackEntry` from libraries, these have to be compiled with `-finfo-table-map`, too.
- Due to optimizations by GHC (e.g. inlining) the stacktrace may change with different GHC parameters and versions.
- The stack trace is empty (by design) if there are no return frames on the stack. (These are pushed every time when a `case ... of` scrutinee is evaluated.)

Since: base-4.17.0.0