Hackage :: [Package]

ghc-stack-annotations: RTS Callstack annotation library

[ bsd, bsd3, development, library ] [ Propose Tags ] [ Report a vulnerability ]

A compatibility library for the RTS Callstack annotations introduced in GHC 9.14. . Allows you to use the stack annotations without having to worry about older GHC versions. As stack annotations rely on the newly introduced AnnFrame stack frame type, this library is operationally a NO-OP for GHC versions below 9.14. . For GHC <9.14, this library exposes an API identical to GHC.Stack.Annotation.Experimental including data types and type classes for writing StackAnnotation instances, without worrying about backwards compatibility. For GHC >=9.14, this library re-exports the API of GHC.Stack.Annotation.Experimental.

[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0
Change log CHANGELOG.md
Dependencies base (>=4.19.1 && <5), ghc-experimental (>=9.1400.0 && <10), ghc-internal (>=9.1400 && <10) [details]
Tested with ghc ==9.14 || ==9.12 || ==9.10 || ==9.8
License BSD-3-Clause
Author Hannes Siebenhandl, Matthew Pickering
Maintainer hannes@well-typed.com
Category development, BSD
Source repo head: git clone https://github.com/well-typed/ghc-stack-annotations
Uploaded by fendor at 2025-12-09T10:52:02Z
Distributions
Downloads 4 total (4 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2025-12-09 [all 1 reports]

Readme for ghc-stack-annotations-0.1.0.0

[back to package description]

ghc-stack-annotations

A compatibility library for the RTS callstack annotations introduced in GHC 9.14.

handleGetRequest :: Int -> IO Int
handleGetRequest number = annotateStackStringIO "My User Annotation" $ do
    bigOperationThatCouldFail number

The annotation primop called by handleGetRequest pushes a stack frame which contains a user-annotation. The stack decoding logic can interpret these frames and display the user-annotated information during exceptions and sample profiling.

Since the annotation primop has only been introduced in GHC-9.14, the annotation functions do not do anything if used on earlier GHC versions.

IPE backtraces which include annotation stack frames offers a number of advantages over the existing backtrace collection mechanisms:

  • It is not necessary to modify the function API (unlike HasCallStack)
  • A "continuous chain" of modifications is not necessary (unlike HasCallStack)
  • The annotations work in all ways of compilation (unlike cost centre stacks)
  • The backtrace is expressed in terms of predictable source locations (unlike some IPE backtraces)

Further, tools such as ghc-stack-profiler can also use the annotation stack frame to provide improved profiles.