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 of the latest supported GHC version. For GHC >=9.14, this library exposes an API identical to GHC.Stack.Annotation.Experimental of the latest supported GHC version. For the latest supported GHC version, we re-export the interface of GHC.Stack.Annotation.Experimental . This API abstracts over the GHC StackAnnotation type class, thus allows you to write instances for all supported GHC versions without any -XCPP.

[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.2.0.0
Change log CHANGELOG.md
Dependencies base (>=4.19.1 && <5), ghc-experimental (>=9.1400.0 && <10.200), unliftio-core (>=0.1 && <0.3) [details]
Tested with ghc ==10.1 || ==9.14 || ==9.12 || ==9.10 || ==9.8
License BSD-3-Clause
Author Hannes Siebenhandl, Matthew Pickering
Maintainer hannes@well-typed.com
Uploaded by fendor at 2026-06-23T14:51:59Z
Category development, BSD
Source repo head: git clone https://github.com/well-typed/ghc-stack-annotations
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 15 total (3 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2026-06-23 [all 1 reports]

Readme for ghc-stack-annotations-0.2.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.