package eio

  1. Overview
  2. Docs
Effect-based direct-style IO API for OCaml

Install 

dune-project
 Dependency

github.com Readme Changelog ISC License Edit opam file Versions (19)

Authors

  1. A
    Anil Madhavapeddy
  2. T
    Thomas Leonard

Maintainers

  1. A
    anil@recoil.org

Sources

eio-1.3.tbz
sha256=8ed5c13e6689f31c85dca5f12762d84b8cc0042a7b07d3e464df6eb4b72b3dfc
sha512=46e8f817f32c3316e7f35835a136ad177a295b3306351eb2efa2386482b0169a5b19ed2925b32da2a1f10d40f083fe3d588dd401908f9fec6e4a44cd68535204

doc/eio/Eio/Exn/index.html

Module Eio.ExnSource

Eio exceptions.

Sourcetype with_bt = exn * Printexc.raw_backtrace
Sourcetype 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.

Sourcetype context

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

Sourceexception 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.

Sourcetype 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.

    *)
Sourceval create : err -> exn

create err is an Io exception with an empty context.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval pp_err : err Fmt.t

pp_err formats an error code.

Sourceval empty_backtrace : Printexc.raw_backtrace

A backtrace with no frames.

Sourcemodule Backend : sig ... end

Extensible backend-specific exceptions.

Sourcetype 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.

    *)
Sourceexception 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.

Sourceval 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 _).