Module Eio.Exn

Eio exceptions.

type with_bt = exn * Printexc.raw_backtrace
type err = ..

Describes the particular error that occurred.

They are typically nested (e.g. Fs (Permission_denied (Unix_error ...))) so that you can match e.g. all IO errors, all file-system errors, all permission denied errors, etc.

If you extend this, use register_pp to add a printer for the new error.

type context

Extra information attached to an IO error. This provides contextual information about what caused the error.

exception Io of err * context

A general purpose IO exception.

This is used for most errors interacting with the outside world, and is similar to Unix.Unix_error, but more general. An unknown Io error should typically be reported to the user, but does not generally indicate a bug in the program.

type err +=
  1. | Multiple_io of (err * context * Printexc.raw_backtrace) list
    (*

    Error code used when multiple IO errors occur.

    This is useful if you want to catch and report all IO errors.

    *)
val create : err -> exn

create err is an Io exception with an empty context.

val add_context : exn -> ('a, Format.formatter, unit, exn) format4 -> 'a

add_context ex msg returns a new exception with msg added to ex's context, if ex is an Io exception.

If ex is not an Io exception, this function just returns the original exception.

val reraise_with_context : exn -> Printexc.raw_backtrace -> ('a, Format.formatter, unit, 'b) format4 -> 'a

reraise_with_context ex bt msg raises ex extended with additional information msg.

ex should be an Io exception (if not, is re-raised unmodified).

Example:

try connect addr
with Eio.Io _ as ex ->
  let bt = Printexc.get_raw_backtrace () in
  reraise_with_context ex bt "connecting to %S" addr

You must get the backtrace before calling any other function in the exception handler to prevent corruption of the backtrace.

val register_pp : (Format.formatter -> err -> bool) -> unit

register_pp pp adds pp as a pretty-printer of errors.

pp f err should format err using f, if possible. It should return true on success, or false if it didn't recognise err.

val pp : exn Fmt.t

pp is a formatter for exceptions.

This is similar to Fmt.exn, but can do a better job on Io exceptions because it can format them directly without having to convert to a string first.

val pp_err : err Fmt.t

pp_err formats an error code.

module Backend : sig ... end

Extensible backend-specific exceptions.

type err +=
  1. | X of Backend.t
    (*

    A top-level code for backend errors that don't yet have a cross-platform classification in Eio.

    You should avoid matching on these (in portable code). Instead, request a proper Eio code for them.

    *)
exception Multiple of with_bt list

Raised if multiple fibers fail, to report all the exceptions.

This usually indicates a bug in the program.

Note: If multiple IO errors occur, then you will get Io (Multiple_io _, _) instead of this.

val combine : with_bt -> with_bt -> with_bt

combine x y returns a single exception and backtrace to use to represent two errors.

The resulting exception is typically just Multiple [y; x], but various heuristics are used to simplify the result:

  • Combining with a Cancel.Cancelled exception does nothing, as these don't need to be reported. The result is only Cancelled if there is no other exception available.
  • If both errors are Io errors, then the result is Io (Multiple_io _).