GHC.Stack.Types

base-4.22.0.0: Core data structures and operations

Copyright | (c) The University of Glasgow 2015
License | see libraries/ghc-prim/LICENSE
Maintainer | ghc-devs@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | Safe
Language | Haskell2010

GHC.Stack.Types

Contents

- Implicit call stacks
- Source locations

Description

Type definitions for implicit call-stacks. Use GHC.Stack from the base package instead of importing this module directly.

The API of this module is unstable and not meant to be consumed by the general public. If you absolutely must depend on it, make sure to use a tight upper bound, e.g., `base < 4.X` rather than `base < 5`, because the interface can change rapidly without much warning.

Synopsis

- data CallStack
  - = EmptyCallStack
  - | PushCallStack [Char] SrcLoc CallStack
  - | FreezeCallStack CallStack
- type HasCallStack = ?callStack :: CallStack
- emptyCallStack :: CallStack
- freezeCallStack :: CallStack -> CallStack
- fromCallSiteList :: [([Char], SrcLoc)] -> CallStack
- getCallStack :: CallStack -> [([Char], SrcLoc)]
- pushCallStack :: ([Char], SrcLoc) -> CallStack -> CallStack
- data SrcLoc = SrcLoc {
  - srcLocPackage :: [Char]
  - srcLocModule :: [Char]
  - srcLocFile :: [Char]
  - srcLocStartLine :: !Int
  - srcLocStartCol :: !Int
  - srcLocEndLine :: !Int
  - srcLocEndCol :: !Int
  }

# Implicit call stacks

data CallStack Source #

`CallStack`s are a lightweight method of obtaining a partial call-stack at any point in the program.

A function can request its call-site with the `HasCallStack` constraint. For example, we can define

    putStrLnWithCallStack :: HasCallStack => String -> IO ()

as a variant of `putStrLn` that will get its call-site and print it, along with the string given as argument. We can access the call-stack inside `putStrLnWithCallStack` with `callStack`.

    >>> :{
    putStrLnWithCallStack :: HasCallStack => String -> IO ()
    putStrLnWithCallStack msg = do
      putStrLn msg
      putStrLn (prettyCallStack callStack)
    :}

Thus, if we call `putStrLnWithCallStack` we will get a formatted call-stack alongside our string.

    >>> putStrLnWithCallStack "hello"
    hello
    CallStack (from HasCallStack):
      putStrLnWithCallStack, called at <interactive>:... in interactive:Ghci...

GHC solves `HasCallStack` constraints in three steps:

1. If there is a `CallStack` in scope -- i.e. the enclosing function has a `HasCallStack` constraint -- GHC will append the new call-site to the existing `CallStack`.
2. If there is no `CallStack` in scope -- e.g. in the GHCi session above -- and the enclosing definition does not have an explicit type signature, GHC will infer a `HasCallStack` constraint for the enclosing definition (subject to the monomorphism restriction).
3. If there is no `CallStack` in scope and the enclosing definition has an explicit type signature, GHC will solve the `HasCallStack` constraint for the singleton `CallStack` containing just the current call-site.

`CallStack`s do not interact with the RTS and do not require compilation with `-prof`. On the other hand, as they are built up explicitly via the `HasCallStack` constraints, they will generally not contain as much information as the simulated call-stacks maintained by the RTS.

A `CallStack` is a `[(String, SrcLoc)]`. The `String` is the name of function that was called, the `SrcLoc` is the call-site. The list is ordered with the most recently called function at the head.

NOTE: The intrepid user may notice that `HasCallStack` is just an alias for an implicit parameter `?callStack :: CallStack`. This is an implementation detail and should not be considered part of the `CallStack` API, we may decide to change the implementation in the future.

Since: base-4.8.1.0

Constructors

EmptyCallStack |
PushCallStack [Char] SrcLoc CallStack |
FreezeCallStack CallStack | Freeze the stack at the given `CallStack`, preventing any further call-sites from being pushed onto it.

#### Instances

Instances details

IsList CallStack Source # | Be aware that 'fromList . toList = id' only for unfrozen `CallStack`s, since `toList` removes frozenness information. Since: base-4.9.0.0
Instance details Defined in GHC.Internal.IsList Associated Types
type Item CallStack |
Instance details Defined in GHC.Internal.IsList type Item CallStack = (String, SrcLoc)
Methods fromList :: [Item CallStack] -> CallStack Source # fromListN :: Int -> [Item CallStack] -> CallStack Source # toList :: CallStack -> [Item CallStack] Source #
Show CallStack Source # | Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Show Methods showsPrec :: Int -> CallStack -> ShowS Source # show :: CallStack -> String Source # showList :: [CallStack] -> ShowS Source #
type Item CallStack Source # |
Instance details Defined in GHC.Internal.IsList type Item CallStack = (String, SrcLoc)

type HasCallStack = ?callStack :: CallStack Source #

Request a CallStack.

NOTE: The implicit parameter `?callStack :: CallStack` is an implementation detail and should not be considered part of the `CallStack` API, we may decide to change the implementation in the future.

Since: base-4.9.0.0

emptyCallStack :: CallStack Source #

The empty `CallStack`.

Since: base-4.9.0.0

freezeCallStack :: CallStack -> CallStack Source #

Freeze a call-stack, preventing any further call-sites from being appended.

    pushCallStack callSite (freezeCallStack callStack) = freezeCallStack callStack

Since: base-4.9.0.0

fromCallSiteList :: [([Char], SrcLoc)] -> CallStack Source #

Convert a list of call-sites to a `CallStack`.

Since: base-4.9.0.0

getCallStack :: CallStack -> [([Char], SrcLoc)] Source #

Extract a list of call-sites from the `CallStack`.

The list is ordered by most recent call.

Since: base-4.8.1.0

pushCallStack :: ([Char], SrcLoc) -> CallStack -> CallStack Source #

Push a call-site onto the stack.

This function has no effect on a frozen `CallStack`.

Since: base-4.9.0.0

# Source locations

data SrcLoc Source #

A single location in the source code.

Since: base-4.8.1.0

Constructors

SrcLoc |
Fields srcLocPackage :: [Char] srcLocModule :: [Char] srcLocFile :: [Char] srcLocStartLine :: !Int srcLocStartCol :: !Int srcLocEndLine :: !Int srcLocEndCol :: !Int

#### Instances

Instances details

Eq SrcLoc Source # | Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Stack.Types Methods (==) :: SrcLoc -> SrcLoc -> Bool Source # (/=) :: SrcLoc -> SrcLoc -> Bool Source #
Generic SrcLoc Source # |
Instance details Defined in GHC.Internal.Generics Associated Types
type Rep SrcLoc | Since: base-4.15.0.0
Instance details Defined in GHC.Internal.Generics type Rep SrcLoc = D1 ('MetaData "SrcLoc" "GHC.Internal.Stack.Types" "ghc-internal" 'False) (C1 ('MetaCons "SrcLoc" 'PrefixI 'True) ((S1 ('MetaSel ('Just "srcLocPackage") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Char]) :*: (S1 ('MetaSel ('Just "srcLocModule") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Char]) :*: S1 ('MetaSel ('Just "srcLocFile") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Char]))) :*: ((S1 ('MetaSel ('Just "srcLocStartLine") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel ('Just "srcLocStartCol") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int)) :*: (S1 ('MetaSel ('Just "srcLocEndLine") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel ('Just "srcLocEndCol") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int)))))
Methods from :: SrcLoc -> Rep SrcLoc x Source # to :: Rep SrcLoc x -> SrcLoc Source #
Show SrcLoc Source # | Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Show Methods showsPrec :: Int -> SrcLoc -> ShowS Source # show :: SrcLoc -> String Source # showList :: [SrcLoc] -> ShowS Source #
type Rep SrcLoc Source # | Since: base-4.15.0.0
Instance details Defined in GHC.Internal.Generics type Rep SrcLoc = D1 ('MetaData "SrcLoc" "GHC.Internal.Stack.Types" "ghc-internal" 'False) (C1 ('MetaCons "SrcLoc" 'PrefixI 'True) ((S1 ('MetaSel ('Just "srcLocPackage") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Char]) :*: (S1 ('MetaSel ('Just "srcLocModule") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Char]) :*: S1 ('MetaSel ('Just "srcLocFile") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Char]))) :*: ((S1 ('MetaSel ('Just "srcLocStartLine") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel ('Just "srcLocStartCol") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int)) :*: (S1 ('MetaSel ('Just "srcLocEndLine") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel ('Just "srcLocEndCol") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Int)))))