:: a typeCtrl KGHC 10.0.0.20260917 · lts/ghc-10.0.x · fc4e598 · 2026-10-11
Moduleghc-experimental-10.0.0Haskell2010
Push user-defined annotation stack frames into the Haskell call stack. Annotation stack frames may be decoded when unwinding the call stack, allowing the user to gain more control over what an IPE stack trace looks like.
The main advantages of stack frame annotations over other Backtraces:
Function signatures don't need to be modified to improve stack traces (e.g. via HasCallStack).
Annotation are arbitrary user-defined datatypes, not just source locations.
Stack frame annotations are always present and do not require recompilation (e.g. -prof or -g3).
The SomeStackAnnotation type is the root of the stack annotation type hierarchy.
When the call stack is annotated with a value of type a, behind the scenes it is
encapsulated in a SomeStackAnnotation.
SomeStackAnnotation :: (Typeable a, StackAnnotation a) => a -> SomeStackAnnotationStackAnnotation SomeStackAnnotationDefined in ghc-internal-10.0.0 · GHC.Internal.Stack.AnnotationStackAnnotations are types which can be pushed onto the call stack
as the payload of AnnFrame stack frames.
displayStackAnnotation :: a -> StringDisplay a human readable string for the StackAnnotation.
This is supposed to be the long version of displayStackAnnotationShort and may contain a source location.
If not provided, displayStackAnnotation is derived from stackAnnotationSourceLocation and displayStackAnnotationShort.
stackAnnotationSourceLocation :: a -> Maybe SrcLocGet the SrcLoc of the given StackAnnotation.
This is optional, SrcLoc are not strictly required for StackAnnotation, but it is still heavily encouarged to provide a SrcLoc for better IPE backtraces.
displayStackAnnotationShort :: a -> StringThe description of the StackAnnotation without any metadata such as source locations.
Pefer implementing displayStackAnnotationShort over displayStackAnnotation.
StackAnnotation CallStackAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalDisplays the first entry of the CallStack
StackAnnotation ShowAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalStackAnnotation StringAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalStackAnnotation SomeStackAnnotationDefined in ghc-internal-10.0.0 · GHC.Internal.Stack.AnnotationUse the Show instance of a type to display as the StackAnnotation.
ShowAnnotation :: Show a => !Maybe SrcLoc -> a -> ShowAnnotationStackAnnotation ShowAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalA String only annotation with an optional source location.
StringAnnotation :: !Maybe SrcLoc -> String -> StringAnnotationStackAnnotation StringAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalShow CallStackAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalStackAnnotation CallStackAnnotationDefined in ghc-experimental-10.0.0 · GHC.Stack.Annotation.ExperimentalDisplays the first entry of the CallStack
annotateStackIO showable b annotates the evaluation stack of b
with the value showable.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
annotateStackStringIO msg b annotates the evaluation stack of b
with the value msg.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
annotateStackShowIO msg b annotates the evaluation stack of b
with the value msg.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
annotateCallStackIO b annotates the evaluation stack of b with the
current callstack.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
These variants all evaluate the code to be annotated to WHNF. Otherwise, the stack annotations will not be shown in stack traces, as the computation is immediately "evaluated" to a thunk, popping the annotation frames from the stack. If the pure computation throws an exception later, the annotation frame will not be present, thus missing in the stack trace.
Note, you will encounter similar issues if the exception is thrown
during evaluation of a nested value, for example Just (error "Oh, no!").
annotateStack anno b annotates the evaluation stack of b
with the value of anno.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
WARNING: forces the evaluation of b to WHNF.
annotateStackString msg b annotates the evaluation stack of b
with the value msg.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
WARNING: forces the evaluation of b to WHNF.
annotateStackShow showable b annotates the evaluation stack of b
with the value showable.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
WARNING: forces the evaluation of b to WHNF.
annotateCallStack b annotates the evaluation stack of b
with the current callstack.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
WARNING: forces the evaluation of b to WHNF.