Dealing with stack backtraces.
Backtrace module deals with two different kinds of backtraces:
1. snapshots of the stack obtained on demand (
2. the stack frames unwound when an exception is raised (
Backtrace.t is a snapshot of the stack obtained by calling
Backtrace.get. It is
represented as a string with newlines separating the frames.
sexp_of_t splits the
string at newlines and removes some of the cruft, leaving a human-friendly list of
to_string does not.
Backtrace.Exn has functions for controlling and printing the backtrace of the most
recently raised exception.
When an exception is raised, the runtime "unwinds" the stack, i.e. removes stack frames, until it reaches a frame with an exception handler. It then matches the exception against the patterns in the handler. If the exception matches, then the program continues. If not, then the runtime continues unwinding the stack to the next handler.
am_recording () = true, then the runtime, while it is unwinding the stack, keeps
track of the part of the stack that is unwound. This is available as a human-readable
most_recent (). Calling
am_recording () = false will
yield the empty string.
am_recording () = true, OCaml keeps only a backtrace for the most recently
raised exception. When one raises an exception, OCaml checks if it is physically
equal to the most recently raised exception. If they are equal, then OCaml appends
the string representation of the stack unwound by the current raise to the stored
backtrace. If the exception being raised is not physically equally to the most
recently raised exception, then OCaml starts recording a new backtrace. Thus one must
most_recent before a subsequent
raise of a (physically) distinct exception,
or the backtrace is lost.
The initial value of
am_recording () is determined by the setting of the
environment variable OCAMLRUNPARAM. If OCAMLRUNPARAM is set, then
= true iff the character "b" occurs in OCAMLRUNPARAM. If OCAMLRUNPARAM is not set,
am_recording () is initially true.
This is the same functionality as provided by the OCaml stdlib
most_recent () returns a string containing the stack that was unwound by the
most recently raised exception.