base-4.9.0.0: Basic libraries

Copyright(c) The University of Glasgow 2011
Licensesee libraries/base/LICENSE
Maintainercvs-ghc@haskell.org
Stabilityinternal
Portabilitynon-portable (GHC Extensions)
Safe HaskellTrustworthy
LanguageHaskell2010

GHC.Stack

Contents

Description

Access to GHC's call-stack simulation

Since: 4.5.0.0

Synopsis

Call stacks

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

Deprecated: error appends the call stack now

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

Since: 4.7.0.0

Implicit parameter call stacks

data CallStack

Implicit CallStacks are an alternate method of obtaining the call stack at a given point in the program.

GHC has two built-in rules for solving implicit-parameters of type CallStack.

  1. If the CallStack occurs in a function call, it appends the source location of the call to the CallStack in the environment.
  2. CallStacks that cannot be solved normally (i.e. unbound occurrences) are defaulted to the empty CallStack.

Otherwise implicit CallStacks behave just like ordinary implicit parameters. For example:

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

Will produce the following when evaluated,

ghci> myerror "die"
*** Exception: die
CallStack (from ImplicitParams):
  myerror, called at interactive:2:1 in interactive:Ghci1

CallStacks 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.

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.

Since: 4.8.1.0

emptyCallStack :: CallStack

The empty CallStack.

Since: 4.9.0.0

freezeCallStack :: CallStack -> CallStack

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

pushCallStack callSite (freezeCallStack callStack) = freezeCallStack callStack

Since: 4.9.0.0

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

Extract a list of call-sites from the CallStack.

The list is ordered by most recent call.

Since: 4.8.1.0

popCallStack :: CallStack -> CallStack

Pop the most recent call-site off the CallStack.

This function, like pushCallStack, has no effect on a frozen CallStack.

Since: 4.9.0.0

prettyCallStack :: CallStack -> String

Pretty print CallStack

Since: 4.8.1.0

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

Push a call-site onto the stack.

This function has no effect on a frozen CallStack.

Since: 4.9.0.0

withFrozenCallStack :: (?callStack :: CallStack) => ((?callStack :: CallStack) => a) -> a

Perform some computation without adding new entries to the CallStack.

Since: 4.9.0.0

Source locations

data SrcLoc

A single location in the source code.

Since: 4.8.1.0

prettySrcLoc :: SrcLoc -> String

Pretty print SrcLoc

Since: 4.8.1.0

Internals

clearCCS :: IO a -> IO a