GHC.Stack.Types



Copyright
(c) The University of Glasgow 2015


License
see libraries/ghc-prim/LICENSE


Maintainer
pedro14@example.net


Stability
internal


Portability
non-portable (GHC Extensions)


Safe Haskell
Trustworthy


Language
Haskell2010



Contents

Implicit call stacks
Source locations



Description
type definitions for implicit call-stacks. Use GHC.Stack from the base package instead of importing this module directly.

Implicit call stacksdata CallStack Source 
CallStacks 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
putStrLnWithCallStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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.
putStrLnWithCallStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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 <interactive>:2:1 in interactive:Ghci1

GHC solves HasCallStack constraints in three steps:

If there is a CallStack in scope -- i.e. the enclosing function has a HasCallStack constraint -- GHC will append the new call-site to the existing CallStack.
If there is no 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).
If there is no 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.

CallStacks 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 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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: base-315-597-0255

Constructors


EmptyCallStack
 



PushCallStack [Char] SrcLoc CallStack

 



FreezeCallStack CallStack

Freeze the stack at the given CallStack, preventing any further call-sites from being pushed onto it.




Instances
Instances details


IsList CallStack 

Be aware that 'fromList . toList = id' only for unfrozen CallStacks, since toList removes frozenness information.
Since: base-315-597-0255


Instance detailsDefined in GHC.Exts 
Associated Types
type Item CallStack Source 
 
Methods
fromList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [Item CallStack] -> CallStack Source 
fromListN 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> [Item CallStack] -> CallStack Source 
toList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CallStack -> [Item CallStack] Source 



Show CallStack 
Since: base-315-597-0255

Instance detailsDefined in GHC.Show 
Methods
showsPrec 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> CallStack -> ShowS Source 
show 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CallStack -> String Source 
showList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [CallStack] -> ShowS Source 



 type Item CallStack 
 

Instance detailsDefined in GHC.Exts type Item CallStack = (String, SrcLoc)


type HasCallStack = ?callStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CallStack Source 
Request a CallStack.
NOTE: The implicit parameter ?callStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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: base-315-597-0255
emptyCallStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CallStack Source 
The empty CallStack.
Since: base-315-597-0255
freezeCallStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CallStack -> CallStack Source 
Freeze a call-stack, preventing any further call-sites from being appended.
pushCallStack callSite (freezeCallStack callStack) = freezeCallStack callStack
Since: base-315-597-0255
fromCallSiteList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [([Char], SrcLoc)] -> CallStack Source 
Convert a list of call-sites to a CallStack.
Since: base-315-597-0255
getCallStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CallStack -> [([Char], SrcLoc)] Source 
Extract a list of call-sites from the CallStack.
The list is ordered by most recent call.
Since: base-315-597-0255
pushCallStack 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ([Char], SrcLoc) -> CallStack -> CallStack Source 
Push a call-site onto the stack.
This function has no effect on a frozen CallStack.
Since: base-315-597-0255
Source locationsdata SrcLoc Source 
A single location in the source code.
Since: base-315-597-0255

Constructors


SrcLoc
 


Fields


srcLocPackage 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [Char] 

srcLocModule 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [Char] 

srcLocFile 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [Char] 

srcLocStartLine 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int 

srcLocStartCol 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int 

srcLocEndLine 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int 

srcLocEndCol 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int 





Instances
Instances details


Eq SrcLoc 
Since: base-315-597-0255

Instance detailsDefined in GHC.Stack.Types 
Methods
(==) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 SrcLoc -> SrcLoc -> Bool Source 
(/=) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 SrcLoc -> SrcLoc -> Bool Source 



Show SrcLoc 
Since: base-315-597-0255

Instance detailsDefined in GHC.Show 
Methods
showsPrec 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> SrcLoc -> ShowS Source 
show 8b7c:f320:99b9:690f:4595:cd17:293a:c069 SrcLoc -> String Source 
showList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [SrcLoc] -> ShowS Source 





    
{'path': 'public/docs/haskell~8/libraries/base-4.14.1.0/ghc-stack-types.html', 'source': 'DevDocs.IO'}