base-4.8.2.0: Basic libraries

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

GHC.Stack

Contents

- Call stacks
  - Simulated by the RTS
  - Explicitly created via implicit-parameters
- Internals

Description

Access to GHC's call-stack simulation

Since: 4.5.0.0

Synopsis

- currentCallStack :: IO [String]
- whoCreated :: a -> IO [String]
- errorWithStackTrace :: String -> a
- data CallStack
- getCallStack :: CallStack -> [(String, SrcLoc)]
- showCallStack :: CallStack -> String
- data CostCentreStack
- data CostCentre
- getCurrentCCS :: dummy -> IO (Ptr CostCentreStack)
- getCCSOf :: a -> IO (Ptr CostCentreStack)
- ccsCC :: Ptr CostCentreStack -> IO (Ptr CostCentre)
- ccsParent :: Ptr CostCentreStack -> IO (Ptr CostCentreStack)
- ccLabel :: Ptr CostCentre -> IO CString
- ccModule :: Ptr CostCentre -> IO CString
- ccSrcSpan :: Ptr CostCentre -> IO CString
- ccsToStrings :: Ptr CostCentreStack -> IO [String]
- renderStack :: [String] -> String

# Call stacks

## Simulated by the RTS

currentCallStack :: IO [String]

returns a '[String]' representing the current call stack. This can be useful for debugging.

The implementation uses the call-stack simulation maintined by the profiler, so it only works if the program was compiled with `-prof` and contains suitable SCC annotations (e.g. by using `-fprof-auto`). Otherwise, the list returned is likely to be empty or uninformative.

Since: 4.5.0.0

whoCreated :: a -> IO [String]

Get the stack trace attached to an object.

Since: 4.5.0.0

errorWithStackTrace :: String -> a

Like the function `error`, but appends a stack trace to the error message if one is available.

Since: 4.7.0.0

## Explicitly created via implicit-parameters

data CallStack

`CallStack`s are an alternate method of obtaining the call stack at a given point in the program.

When an implicit-parameter of type `CallStack` occurs in a program, GHC will solve it with the current location. If another `CallStack` implicit-parameter is in-scope (e.g. as a function argument), the new location will be appended to the one in-scope, creating an explicit call-stack. For example,

    myerror :: (?loc :: CallStack) => String -> a
    myerror msg = error (msg ++ "n" ++ showCallStack ?loc)

ghci> myerror "die" *** Exception: die ?loc, called at MyError.hs:7:51 in main:MyError myerror, called at interactive:2:1 in interactive:Ghci1

`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 using implicit-parameters, they will generally not contain as much information as the simulated call-stacks maintained by the RTS.

The `CallStack` type is abstract, but it can be converted into a `[(String, SrcLoc)]` via `getCallStack`. 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.

Since: 4.9.0.0

Instances

Eq CallStack |
Show CallStack |

getCallStack :: CallStack -> [(String, SrcLoc)]

showCallStack :: CallStack -> String

# Internals

data CostCentreStack

data CostCentre

getCurrentCCS :: dummy -> IO (Ptr CostCentreStack)

getCCSOf :: a -> IO (Ptr CostCentreStack)

ccsCC :: Ptr CostCentreStack -> IO (Ptr CostCentre)

ccsParent :: Ptr CostCentreStack -> IO (Ptr CostCentreStack)

ccLabel :: Ptr CostCentre -> IO CString

ccModule :: Ptr CostCentre -> IO CString

ccSrcSpan :: Ptr CostCentre -> IO CString

ccsToStrings :: Ptr CostCentreStack -> IO [String]

renderStack :: [String] -> String