Lwt.backtrace_* functions

Question

I've just noticed the following functions in Lwt.mli:

val backtrace_bind : (exn -> exn) -> 'a t -> ('a -> 'b t) -> 'b t
val backtrace_catch : (exn -> exn) -> (unit -> 'a t) -> (exn -> 'a t) -> 'a t
val backtrace_try_bind : (exn -> exn) -> (unit -> 'a t) -> ('a -> 'b t) -> (exn -> 'b t) -> 'b t
val backtrace_finalize : (exn -> exn) -> (unit -> 'a t) -> (unit -> unit t) -> 'a t

Unfortunately they are undocumented. What do they do?

Answer 1

Some digging in GitHub and documentation shows that these are used internally for propagating backtraces between threads when using pa_lwt and -lwt-debug is passed to camlp4. They are also used for the same purpose by default with ppx_lwt.

The -lwt-debug option is documented on this page: http://ocsigen.org/lwt/2.5.0/manual/ (search the page for "backtrace support" to go to it).

The option to turn this off in ppx_lwt is documented here: https://ocsigen.org/lwt/dev/api/Ppx_lwt (search for -no-debug).

See this commit, which shows that these are used in the code generated by try_lwt, etc.: https://github.com/ocsigen/lwt/commit/78eee34fb6247da38a3d4ea5b7872676181d47e2

Edited: confirmed more things by looking through more code, and incorporated comment.