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
Description
Access to GHC's call-stack simulation
Since: 4.5.0.0
- currentCallStack :: IO [String]
- whoCreated :: a -> IO [String]
- errorWithStackTrace :: String -> a
- data CallStack
- emptyCallStack :: CallStack
- freezeCallStack :: CallStack -> CallStack
- getCallStack :: CallStack -> [([Char], SrcLoc)]
- popCallStack :: CallStack -> CallStack
- prettyCallStack :: CallStack -> String
- pushCallStack :: ([Char], SrcLoc) -> CallStack -> CallStack
- withFrozenCallStack :: (?callStack :: CallStack) => ((?callStack :: CallStack) => a) -> a
- data SrcLoc = SrcLoc {
- srcLocPackage :: [Char]
- srcLocModule :: [Char]
- srcLocFile :: [Char]
- srcLocStartLine :: Int
- srcLocStartCol :: Int
- srcLocEndLine :: Int
- srcLocEndCol :: Int
- prettySrcLoc :: SrcLoc -> String
- data CostCentreStack
- data CostCentre
- getCurrentCCS :: dummy -> IO (Ptr CostCentreStack)
- getCCSOf :: a -> IO (Ptr CostCentreStack)
- clearCCS :: IO a -> IO a
- 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
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
Implicit parameter call stacks
data CallStack
Implicit CallStack
s 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
.
- If the
CallStack
occurs in a function call, it appends the source location of the call to theCallStack
in the environment. CallStack
s that cannot be solved normally (i.e. unbound occurrences) are defaulted to the emptyCallStack
.
Otherwise implicit CallStack
s 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
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.
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
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
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
Constructors
SrcLoc | |
Fields
|
prettySrcLoc :: SrcLoc -> String
Pretty print SrcLoc
Since: 4.8.1.0
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