package trax

  1. Overview
  2. Docs
Stack-independent exception tracing

Install

Dune Dependency

Authors

Maintainers

Sources

v0.4.0.tar.gz
sha256=cd265a9f84b7fd1769c35ab04e92073e446c2c32088159c0e01cc64ab4d14db7
md5=7e056778b183bce0924def2d7722c313

Description

Trax defines a special exception, which is used to store a trace of where the exception was raised and re-raised. This is done independently from the state of the call stack. It can be used with Lwt or other asynchronous computations in which exceptions no longer propagate simply to the calling function but may be caught, stored, and re-raised after a while and after other exceptions have occurred in unrelated computations.

Published: 21 Sep 2021

README

OCaml exception tracing

This small library allows a user or a preprocessor to reliably trace exceptions, i.e. give a list of source code locations through which an exception propagated.

The traditional method consisting in recording the stack trace at the point where an exception is raised is not satisfying. In particular it doesn't allow exceptions to be stored while other functions run and may themselves raise exceptions, resetting the stack trace. Some examples of what works and what doesn't work with stack traces are given here: https://github.com/mjambon/backtrace

Instead of relying on stack traces, Trax wraps the original exception within a special exception together with a trace, i.e. a list of source code locations.

Sample usage

let foo x y z =
  ...
  (* some error occurred *)
  Trax.raise __LOC__ (Failure "uh oh")

let bar x y z =
  try foo x y z
  with e ->
    (* inspect the exception; requires unwrapping *)
    match Trax.unwrap e with
    | Invalid_arg _ ->
       assert false
    | _ ->
       (* re-raise the exception, adding the current location to the trace *)
       Trax.raise __LOC__ e

let main () =
  try
    ...
    bar x y z
    ...
  with e ->
    Trax.print stderr e

Dependencies (2)

  1. dune >= "2.8"
  2. ocaml >= "4.12.0"

Dev Dependencies

None

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.