GHC.Stack (original) (raw)

Documentation

Profiling call stacks

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: base-4.5.0.0

HasCallStack call stacks

data CallStack Source #

[CallStack](GHC-Stack.html#t:CallStack "GHC.Stack")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](GHC-Stack.html#t:HasCallStack "GHC.Stack") 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](GHC-Stack.html#v:callStack "GHC.Stack").

>>> **:{** ****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 :... in interactive:Ghci...

GHC solves [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraints in three steps:

1. If there is a [CallStack](GHC-Stack.html#t:CallStack "GHC.Stack") in scope -- i.e. the enclosing function has a [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraint -- GHC will append the new call-site to the existing [CallStack](GHC-Stack.html#t:CallStack "GHC.Stack").
2. If there is no [CallStack](GHC-Stack.html#t:CallStack "GHC.Stack") 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](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraint for the enclosing definition (subject to the monomorphism restriction).
3. If there is no [CallStack](GHC-Stack.html#t:CallStack "GHC.Stack") in scope and the enclosing definition has an explicit type signature, GHC will solve the [HasCallStack](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraint for the singleton [CallStack](GHC-Stack.html#t:CallStack "GHC.Stack") containing just the current call-site.

[CallStack](GHC-Stack.html#t:CallStack "GHC.Stack")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](GHC-Stack.html#t:HasCallStack "GHC.Stack") constraints, they will generally not contain as much information as the simulated call-stacks maintained by the RTS.

A [CallStack](GHC-Stack.html#t:CallStack "GHC.Stack") is a [(String, SrcLoc)]. The String is the name of function that was called, the [SrcLoc](GHC-Stack.html#t:SrcLoc "GHC.Stack") 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](GHC-Stack.html#t:HasCallStack "GHC.Stack") is just an alias for an implicit parameter ?callStack :: CallStack. This is an implementation detail and should not be considered part of the[CallStack](GHC-Stack.html#t:CallStack "GHC.Stack") API, we may decide to change the implementation in the future.

Since: base-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](GHC-Stack.html#t:CallStack "GHC.Stack") API, we may decide to change the implementation in the future.

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

Source locations

data SrcLoc Source #

A single location in the source code.

Since: base-4.8.1.0

Internals

getCurrentCCS :: dummy -> IO (Ptr CostCentreStack) Source #

Returns the current [CostCentreStack](GHC-Stack.html#t:CostCentreStack "GHC.Stack") (value is nullPtr if the current program was not compiled with profiling support). Takes a dummy argument which can be used to avoid the call to getCurrentCCS being floated out by the simplifier, which would result in an uninformative stack (CAF).

clearCCS :: IO a -> IO a Source #

Run a computation with an empty cost-center stack. For example, this is used by the interpreter to run an interpreted computation without the call stack showing that it was invoked from GHC.