Copyright | (c) The University of Glasgow 2011 |
---|---|
License | see libraries/base/LICENSE |
Maintainer | [email protected] |
Stability | internal |
Portability | non-portable (GHC Extensions) |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
Access to GHC's call-stack simulation
Since: 4.5.0.0
errorWithStackTrace :: String -> a Source
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
currentCallStack :: IO [String] Source
Returns a [String]
representing the current call stack. This can be useful for debugging.
The implementation uses the call-stack simulation maintained 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] Source
Get the stack trace attached to an object.
Since: 4.5.0.0
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
errorWithCallStack :: HasCallStack => String -> a
as a variant of error
that will get its call-site. We can access the call-stack inside errorWithCallStack
with callStack
.
errorWithCallStack :: HasCallStack => String -> a errorWithCallStack msg = error (msg ++ "n" ++ prettyCallStack callStack)
Thus, if we call errorWithCallStack
we will get a formatted call-stack alongside our error message.
>>>
errorWithCallStack "die"
*** Exception: die CallStack (from HasCallStack): errorWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
GHC solves HasCallStack
constraints in three steps:
CallStack
in scope -- i.e. the enclosing function has a HasCallStack
constraint -- GHC will append the new call-site to the existing CallStack
.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).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: 4.8.1.0
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: 4.9.0.0
callStack :: HasCallStack => CallStack Source
Return the current CallStack
.
Does *not* include the call-site of callStack
.
Since: 4.9.0.0
emptyCallStack :: CallStack Source
The empty CallStack
.
Since: 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: 4.9.0.0
fromCallSiteList :: [([Char], SrcLoc)] -> CallStack Source
Convert a list of call-sites to a CallStack
.
Since: 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: 4.8.1.0
popCallStack :: CallStack -> CallStack Source
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 Source
Pretty print a CallStack
.
Since: 4.9.0.0
pushCallStack :: ([Char], SrcLoc) -> CallStack -> CallStack Source
Push a call-site onto the stack.
This function has no effect on a frozen CallStack
.
Since: 4.9.0.0
withFrozenCallStack :: HasCallStack => (HasCallStack => a) -> a Source
Perform some computation without adding new entries to the CallStack
.
Since: 4.9.0.0
A single location in the source code.
Since: 4.8.1.0
SrcLoc | |
Fields
|
prettySrcLoc :: SrcLoc -> String Source
Pretty print a SrcLoc
.
Since: 4.9.0.0
data CostCentreStack Source
data CostCentre Source
getCurrentCCS :: dummy -> IO (Ptr CostCentreStack) Source
getCCSOf :: a -> IO (Ptr CostCentreStack) Source
clearCCS :: IO a -> IO a Source
ccsCC :: Ptr CostCentreStack -> IO (Ptr CostCentre) Source
ccsParent :: Ptr CostCentreStack -> IO (Ptr CostCentreStack) Source
ccLabel :: Ptr CostCentre -> IO CString Source
ccModule :: Ptr CostCentre -> IO CString Source
ccSrcSpan :: Ptr CostCentre -> IO CString Source
ccsToStrings :: Ptr CostCentreStack -> IO [String] Source
renderStack :: [String] -> String Source
© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/8.2.1/docs/html/libraries/base-4.10.0.0/GHC-Stack.html