| Copyright | (c) The GHC Team |
|---|---|
| License | see libraries/ghc-experimental/LICENSE |
| Maintainer | ghc-devs@haskell.org |
| Stability | experimental |
| Portability | non-portable (GHC Extensions) |
| Safe Haskell | None |
| Language | Haskell2010 |
GHC.Stack.Annotation.Experimental
Description
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.
-profor-g3).
Synopsis
- data SomeStackAnnotation where
- SomeStackAnnotation :: forall a. (Typeable a, StackAnnotation a) => a -> SomeStackAnnotation
- class StackAnnotation a where
- displayStackAnnotation :: a -> String
- data ShowAnnotation where
- ShowAnnotation :: forall a. Show a => a -> ShowAnnotation
- data StringAnnotation where
- newtype CallStackAnnotation = CallStackAnnotation CallStack
- annotateStackIO :: (Typeable a, StackAnnotation a) => a -> IO b -> IO b
- annotateStackStringIO :: String -> IO b -> IO b
- annotateStackShowIO :: Show a => a -> IO b -> IO b
- annotateCallStackIO :: HasCallStack => IO a -> IO a
- annotateStack :: (Typeable a, StackAnnotation a) => a -> b -> b
- annotateStackString :: String -> b -> b
- annotateStackShow :: (Typeable a, Show a) => a -> b -> b
- annotateCallStack :: HasCallStack => b -> b
The root of Stack Annotation Types
data SomeStackAnnotation where Source #
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.
Constructors
| SomeStackAnnotation :: forall a. (Typeable a, StackAnnotation a) => a -> SomeStackAnnotation |
Instances
| StackAnnotation SomeStackAnnotation Source # | |
Defined in GHC.Internal.Stack.Annotation Methods displayStackAnnotation :: SomeStackAnnotation -> String Source # | |
Displaying Stack Annotations
class StackAnnotation a where Source #
StackAnnotations are types which can be pushed onto the call stack
as the payload of AnnFrame stack frames.
Methods
displayStackAnnotation :: a -> String Source #
Instances
| StackAnnotation CallStackAnnotation Source # | Displays the first entry of the |
Defined in GHC.Stack.Annotation.Experimental Methods displayStackAnnotation :: CallStackAnnotation -> String Source # | |
| StackAnnotation ShowAnnotation Source # | |
Defined in GHC.Stack.Annotation.Experimental Methods | |
| StackAnnotation StringAnnotation Source # | |
Defined in GHC.Stack.Annotation.Experimental Methods displayStackAnnotation :: StringAnnotation -> String Source # | |
| StackAnnotation SomeStackAnnotation Source # | |
Defined in GHC.Internal.Stack.Annotation Methods displayStackAnnotation :: SomeStackAnnotation -> String Source # | |
Annotation helpers
data ShowAnnotation where Source #
Use the Show instance of a type to display as the StackAnnotation.
Constructors
| ShowAnnotation :: forall a. Show a => a -> ShowAnnotation |
Instances
| StackAnnotation ShowAnnotation Source # | |
Defined in GHC.Stack.Annotation.Experimental Methods | |
data StringAnnotation where Source #
Constructors
| StringAnnotation :: String -> StringAnnotation |
Instances
| StackAnnotation StringAnnotation Source # | |
Defined in GHC.Stack.Annotation.Experimental Methods displayStackAnnotation :: StringAnnotation -> String Source # | |
CallStack annotations
newtype CallStackAnnotation Source #
A CallStack stack annotation.
Constructors
| CallStackAnnotation CallStack |
Instances
| Show CallStackAnnotation Source # | |
Defined in GHC.Stack.Annotation.Experimental | |
| StackAnnotation CallStackAnnotation Source # | Displays the first entry of the |
Defined in GHC.Stack.Annotation.Experimental Methods displayStackAnnotation :: CallStackAnnotation -> String Source # | |
Push stack frame annotations in IO code.
annotateStackIO :: (Typeable a, StackAnnotation a) => a -> IO b -> IO b Source #
annotateStackIO showable bb
with the value showable.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
annotateStackStringIO :: String -> IO b -> IO b Source #
annotateStackStringIO msg bb
with the value msg.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
annotateStackShowIO :: Show a => a -> IO b -> IO b Source #
annotateStackShowIO msg bb
with the value msg.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
annotateCallStackIO :: HasCallStack => IO a -> IO a Source #
annotateCallStackIO bb with the
current callstack.
When decoding the call stack, the annotation frames can be used to add more information to stack traces.
Push stack frame annotations in non-IO code.
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 :: (Typeable a, StackAnnotation a) => a -> b -> b Source #
annotateStack anno bb
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 :: String -> b -> b Source #
annotateStackString msg bb
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 :: (Typeable a, Show a) => a -> b -> b Source #
annotateStackShow showable bb
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 :: HasCallStack => b -> b Source #
annotateCallStack bb
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.