Module Base.ExnSource

Exceptions.

sexp_of_t uses a global table of sexp converters. To register a converter for a new exception, add [@@deriving sexp] to its definition. If no suitable converter is found, the standard converter in Printexc will be used to generate an atomic S-expression.

Sourcetype t = exn
Sourceval sexp_of_t : t -> Sexplib0.Sexp.t
include Pretty_printer.S with type t := t
Sourceval pp : Formatter.t -> t -> unit
Sourceexception Finally of t * t

Raised when finalization after an exception failed, too. The first exception argument is the one raised by the initial function, the second exception the one raised by the finalizer.

Sourceexception Reraised of string * t
Sourceval create_s : Sexp.t -> t

create_s sexp returns an exception t such that phys_equal (sexp_of_t t) sexp. This is useful when one wants to create an exception that serves as a message and the particular exn constructor doesn't matter.

Sourceval raise_without_backtrace : t -> _

Same as raise, except that the backtrace is not recorded.

Sourceval raise_with_original_backtrace : t -> Printexc.raw_backtrace -> _

raise_with_original_backtrace t bt raises the exception exn, recording bt as the backtrace it was originally raised at. This is useful to re-raise exceptions annotated with extra information.

Sourceval reraise : t -> string -> _
Sourceval reraisef : t -> ('a, unit, string, unit -> _) format4 -> 'a

Types with format4 are hard to read, so here's an example.

  let foobar str =
    try
      ...
    with exn ->
      Exn.reraisef exn "Foobar is buggy on: %s" str ()
Sourceval to_string : t -> string

Human-readable, multi-line.

Sourceval to_string_mach : t -> string

Machine format, single-line.

Sourceval protectx : f:('a -> 'b) -> 'a -> finally:('a -> unit) -> 'b

Executes f and afterwards executes finally, whether f throws an exception or not.

Sourceval protect : f:(unit -> 'a) -> finally:(unit -> unit) -> 'a
Sourceval handle_uncaught : exit:bool -> (unit -> unit) -> unit

handle_uncaught ~exit f catches an exception escaping f and prints an error message to stderr. Exits with return code 1 if exit is true, and returns unit otherwise.

Note that since OCaml 4.02.0, you don't need to use this at the entry point of your program, as the OCaml runtime will do better than this function.

Sourceval handle_uncaught_and_exit : (unit -> 'a) -> 'a

handle_uncaught_and_exit f returns f (), unless that raises, in which case it prints the exception and exits nonzero.

Sourceval reraise_uncaught : string -> (unit -> 'a) -> 'a

Traces exceptions passing through. Useful because in practice, backtraces still don't seem to work.

Example:

  let rogue_function () = if Random.bool () then failwith "foo" else 3
  let traced_function () = Exn.reraise_uncaught "rogue_function" rogue_function
                             traced_function ();;
: Program died with Reraised("rogue_function", Failure "foo")
Sourceval does_raise : (unit -> _) -> bool

does_raise f returns true iff f () raises, which is often useful in unit tests.

Sourceval is_phys_equal_most_recent : t -> bool

Returns true if this exception is physically equal to the most recently raised one. If so, then Backtrace.Exn.most_recent () is a backtrace corresponding to this exception.

Note that, confusingly, exceptions can be physically equal even if the caller was not involved in handling of the last-raised exception. See the documentation of Backtrace.Exn.most_recent_for_exn for further discussion.

Sourceval initialize_module : unit -> unit

User code never calls this. It is called in base.ml as a top-level side effect to change the display of exceptions and install an uncaught-exception printer.