package tezos-error-monad

Categories of error

Note: this is only meaningful within the protocol. It may be removed from the error monad and pushed to the protocol environment in the future. See https://gitlab.com/tezos/tezos/-/issues/1576

The main error type.

Whenever you add a variant to this type (with type Error_monad.error += …) you must also register the error with register_error_kind (or register_recursive_error_kind if the error payload contains errors).

These errors are not meant to be inspected in general. Meaning that they should not be matched upon. Consequently it is acceptable to register an error in an implementation file and not mention it in the corresponding interface file.

TzTrace: trace module specific to the Tezos Error monad. The trace type of this module is meant to become abstract in the medium-term (see https://gitlab.com/tezos/tezos/-/issues/1577).

Syntax module (with let and returns) for the TzResult monad (i.e., the TzTraced Result monad).

Syntax module (with let and returns) for the TzResult+Lwt monad (i.e., the Lwt TzTraced Result monad

error_with fmt … errors out: it fails within the TracedResult monad. The payload of the Error constructor is unspecified beyond the fact that it includes the string formatted by fmt …. E.g.,

if n < 0 then
   error_with "Index (%d) is negative" n
else if n >= Array.length a then
   error_with "Index (%d) is beyond maximum index (%d)" n (Array.length a - 1)
else
   Ok a.(n)

Note: this is somewhat equivalent to Stdlib.failwith in that it is a generic failure mechanism with a simple error message. Like Stdlib.failwith it should be replaced by a more specific error mechanism in most cases.

failwith fmt … fails: it fails within the LwtTracedResult monad. The payload of the Error constructor is unspecified beyond the fact that it includes the string formatted by fmt …. E.g.,

match find key store with
| None ->
   failwith "Key %a not found in store" pp_key key
| Some value ->
   LwtResult.return value

Note: this is somewhat equivalent to Stdlib.failwith in that it is a generic failure mechanism with a simple error message. Like Stdlib.failwith it should be replaced by a more specific error mechanism in most cases.

error_with_exn exc errors out: it fails within the TracedResult monad. The payload of the Error constructor is unspecified but it includes the exception.

It is meant as a way to switch from exception-based error management to tzresult-based error management, e.g., when calling external libraries that use exceptions.

try Ok (parse_input s) with Lex_error | Parse_error as exc -> error_with_exn exc

Whilst it is useful in specific places, it is generally better to use a dedicated error.

fail_with_exn exc fails: it fails within the LwtTracedResult monad. The payload of the Error constructor is unspecified but it includes the info from the exception.

It is meant as a way to switch, inside of Lwt code, from exception-based error management to tzresult-based error management, e.g., when calling external libraries that use exceptions.

Lwt.catch
   (fun () -> parse_input s)
   (function
      | Lex_error | Parse_error as exc -> fail_with_exn exc
      | exn -> raise exn (* re-raise by default *))

Whilst it is useful in specific places, it is generally better to use a dedicated error.

error_of_exn e is an error that carries the exception e. This function is intended to be used when interacting with a part of the code (most likely an external library) which uses exceptions.

error_of_fmt … is like error_with … but the error isn't wrapped in a trace in a result. Instead, an error is returned and the caller is expected to pass it to whichever error-combinator is appropriate to the situation. E.g.,

fail_unless (check_valid input) (error_of_fmt "Invalid_input: %a" pp input)

Wrapped OCaml/Lwt exception

Cancelation

protect is a wrapper around Lwt.catch where the error handler operates over trace instead of exn. Besides, protect ~on_error ~canceler ~f may *cancel* f via a Lwt_canceler.t.

More precisely, protect ~on_error ~canceler f runs f (). An Lwt failure triggered by f () is wrapped into an Exn. If a canceler is given and Lwt_canceler.cancellation canceler is determined before f (), a Canceled error is returned.

Errors are caught by ~on_error (if given), otherwise the previous value is returned. An Lwt failure triggered by ~on_error is wrapped into an Exn

catch f executes f within a try-with block and wraps exceptions within a tzresult. catch f is equivalent to try Ok (f ()) with e -> Error (error_of_exn e).

If catch_only is set, then only exceptions e such that catch_only e is true are caught.

Whether catch_only is set or not, this function never catches non-deterministic runtime exceptions of OCaml such as Stack_overflow and Out_of_memory.

catch_e is like catch but when f returns a tzresult. I.e., catch_e f is equivalent to try f () with e -> Error (error_of_exn e).

catch_only has the same use as with catch. The same restriction on catching non-deterministic runtime exceptions applies.

catch_f f handler is equivalent to map_error (catch f) handler. In other words, it catches exceptions in f () and either returns the value in an Ok or passes the exception to handler for the Error.

No attempt is made to catch the exceptions raised by handler.

catch_only has the same use as with catch. The same restriction on catching non-deterministic runtime exceptions applies.

catch_s is like catch but when f returns a promise. It is equivalent to

Lwt.try_bind f
  (fun v -> Lwt.return (Ok v))
  (fun e -> Lwt.return (Error (error_of_exn e)))

catch_only has the same use as with catch. The same restriction on catching non-deterministic runtime exceptions applies.

catch_es is like catch_s but when f returns a promise of a tzresult. I.e., catch_es f is equivalent to Lwt.catch f (fun e -> Lwt.return_error (error_of_exn e)).

catch_only has the same use as with catch. The same restriction on catching non-deterministic runtime exceptions applies.