Tezos Protocol Implementation - Error Monad
type error_category = [ | `BranchErrors that may not happen in another context
*)| `TemporaryErrors that may not happen in a later context
*)| `PermanentErrors that will happen no matter the context
*) ]Categories of error
type error = Tezos_error_monad.TzCore.error = ..include Tezos_error_monad.Sig.CORE with type error := errorval error_encoding : error Data_encoding.tval pp : Stdlib.Format.formatter -> error -> unitinclude Tezos_error_monad.Sig.EXT with type error := errorval register_error_kind :
Tezos_error_monad.Sig.error_category ->
id:string ->
title:string ->
description:string ->
?pp:(Stdlib.Format.formatter -> 'err -> unit) ->
'err Data_encoding.t ->
(error -> 'err option) ->
('err -> error) ->
unitThe error data type is extensible. Each module can register specialized error serializers id unique name of this error. Ex.: overflow_time_counter title more readable name. Ex.: Overflow of time counter description human readable description. Ex.: The time counter overflowed while computing delta increase pp formatter used to pretty print additional arguments. Ex.: The time counter overflowed while computing delta increase. Previous value %d. Delta: %d encoder decoder data encoding for this error. If the error has no value, specify Data_encoding.empty
val register_recursive_error_kind :
Tezos_error_monad.Sig.error_category ->
id:string ->
title:string ->
description:string ->
pp:(Stdlib.Format.formatter -> 'err -> unit) ->
(error Data_encoding.t -> 'err Data_encoding.t) ->
(error -> 'err option) ->
('err -> error) ->
unitSame as register_error_kind but allow errors to wrap other errors.
The encoding argument is a function which will be given the encoding of errors as argument so that you can encode errors in errors using a fixpoint.
Another difference with register_error_kind is that pp is mandatory.
val classify_error : error -> Tezos_error_monad.Sig.error_categoryClassify an error using the registered kinds
Catch all error when 'serializing' an error.
val json_of_error : error -> Data_encoding.jsonAn error serializer
val error_of_json : Data_encoding.json -> errortype error_info = Tezos_error_monad.Error_monad.error_info = {category : Tezos_error_monad.Sig.error_category;id : string;title : string;description : string;schema : Data_encoding.json_schema;}Error information
val pp_info : Stdlib.Format.formatter -> error_info -> unitval find_info_of_error : error -> error_infofind_info_of_error e retrieves the `error_info` associated with the given error `e`.
val get_registered_errors : unit -> error_info listRetrieves information of registered errors
include Tezos_error_monad.Sig.WITH_WRAPPED with type error := errormodule type Wrapped_error_monad =
Tezos_error_monad.Error_monad.Wrapped_error_monadval register_wrapped_error_kind :
(module Wrapped_error_monad) ->
id:string ->
title:string ->
description:string ->
unitSame as register_error_kind but for a wrapped error monad. The codec is defined in the module parameter. It makes the category of the error Wrapped instead of Main.
module TzTrace = Tezos_error_monad.Error_monad.TzTracetype 'error trace = 'error TzTrace.traceinclude Tezos_error_monad.Sig.MONAD
with type 'error trace := 'error TzTrace.traceval return : 'a -> ('a, 'trace) Stdlib.result Lwt.tSuccessful return
val return_unit : (unit, 'trace) Stdlib.result Lwt.tSuccessful return of ()
val return_none : ('a option, 'trace) Stdlib.result Lwt.tSuccessful return of None
val return_some : 'a -> ('a option, 'trace) Stdlib.result Lwt.treturn_some x is a successful return of Some x
val return_nil : ('a list, 'trace) Stdlib.result Lwt.tSuccessful return of []
val return_true : (bool, 'trace) Stdlib.result Lwt.tSuccessful return of true
val return_false : (bool, 'trace) Stdlib.result Lwt.tSuccessful return of false
val error : 'err -> ('a, 'err TzTrace.trace) Stdlib.resultErroneous result
val fail : 'err -> ('a, 'err TzTrace.trace) Stdlib.result Lwt.tErroneous return
Infix operators for monadic binds/maps. All operators follow this naming convention:
>> for bind and | for map= for Lwt or ? for Error= for Lwt or ? for Error, it is only used for operator that are within both monads.Lwt's bind reexported. Following Lwt's convention, in this operator and the ones below, = indicate we operate within Lwt.
Lwt's map reexported. The | indicates a map rather than a bind.
val (>>?) :
('a, 'trace) Stdlib.result ->
('a -> ('b, 'trace) Stdlib.result) ->
('b, 'trace) Stdlib.resultNon-Lwt bind operator. In this operator and the ones below, ? indicates that we operate within the error monad.
Non-Lwt map operator.
val (>>=?) :
('a, 'trace) Stdlib.result Lwt.t ->
('a -> ('b, 'trace) Stdlib.result Lwt.t) ->
('b, 'trace) Stdlib.result Lwt.tCombined bind operator. The =? indicates that the operator acts within the combined error-lwt monad.
Combined map operator.
val (>>?=) :
('a, 'trace) Stdlib.result ->
('a -> ('b, 'trace) Stdlib.result Lwt.t) ->
('b, 'trace) Stdlib.result Lwt.tInjecting bind operator. This is for transitioning from the simple Error monad to the combined Error-Lwt monad.
Note the order of the character: it starts with the error monad marker ? and has the Lwt monad marker later. This hints at the role of the operator to transition into Lwt.
Injecting map operator.
val record_trace :
'err ->
('a, 'err TzTrace.trace) Stdlib.result ->
('a, 'err TzTrace.trace) Stdlib.resultEnrich an error report (or do nothing on a successful result) manually
val trace :
'err ->
('b, 'err TzTrace.trace) Stdlib.result Lwt.t ->
('b, 'err TzTrace.trace) Stdlib.result Lwt.tAutomatically enrich error reporting on stack rewind
val record_trace_eval :
(unit -> ('err, 'err TzTrace.trace) Stdlib.result) ->
('a, 'err TzTrace.trace) Stdlib.result ->
('a, 'err TzTrace.trace) Stdlib.resultSame as record_trace, for unevaluated error
val trace_eval :
(unit -> ('err, 'err TzTrace.trace) Stdlib.result Lwt.t) ->
('b, 'err TzTrace.trace) Stdlib.result Lwt.t ->
('b, 'err TzTrace.trace) Stdlib.result Lwt.tSame as trace, for unevaluated Lwt error
val error_unless : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.resultError on failed assertion
val error_when : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.resultval fail_unless :
bool ->
'err ->
(unit, 'err TzTrace.trace) Stdlib.result Lwt.tErroneous return on failed assertion
val fail_when : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.result Lwt.tval dont_wait :
(exn -> unit) ->
('trace -> unit) ->
(unit -> (unit, 'trace) Stdlib.result Lwt.t) ->
unitWrapper around Lwt_utils.dont_wait
val join_e :
(unit, 'err TzTrace.trace) Stdlib.result list ->
(unit, 'err TzTrace.trace) Stdlib.resultSimilar functions in the error monad
val all_e :
('a, 'err TzTrace.trace) Stdlib.result list ->
('a list, 'err TzTrace.trace) Stdlib.resultval both_e :
('a, 'err TzTrace.trace) Stdlib.result ->
('b, 'err TzTrace.trace) Stdlib.result ->
('a * 'b, 'err TzTrace.trace) Stdlib.resultval join_ep :
(unit, 'err TzTrace.trace) Stdlib.result Lwt.t list ->
(unit, 'err TzTrace.trace) Stdlib.result Lwt.tSimilar functions in the combined monad
val all_ep :
('a, 'err TzTrace.trace) Stdlib.result Lwt.t list ->
('a list, 'err TzTrace.trace) Stdlib.result Lwt.tval both_ep :
('a, 'err TzTrace.trace) Stdlib.result Lwt.t ->
('b, 'err TzTrace.trace) Stdlib.result Lwt.t ->
('a * 'b, 'err TzTrace.trace) Stdlib.result Lwt.tinclude Tezos_error_monad.Sig.MONAD_EXT
with type error := error
and type 'error trace := 'error TzTrace.tracetype tztrace = error TzTrace.tracetype 'a tzresult = ('a, tztrace) Stdlib.resultval classify_errors : tztrace -> Tezos_error_monad.Sig.error_categoryval pp_print_error : Stdlib.Format.formatter -> error TzTrace.trace -> unitval pp_print_error_first :
Stdlib.Format.formatter ->
error TzTrace.trace ->
unitPretty prints a trace as the message of its first error
val trace_encoding : error TzTrace.trace Data_encoding.tval result_encoding : 'a Data_encoding.t -> 'a tzresult Data_encoding.tA serializer for result of a given type
val generic_error :
('a, Stdlib.Format.formatter, unit, 'b tzresult) Stdlib.format4 ->
'aErroneous result (shortcut for generic errors)
Erroneous return (shortcut for generic errors)
val error_exn : exn -> 'a tzresulterror_of_exn e is a trace 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 exception. E.g.,
try
Ok (make_some_call parameter)
with
| (Not_found | Failure _) as e ->
Error (error_of_exn e)val failure : ('a, Stdlib.Format.formatter, unit, error) Stdlib.format4 -> 'aWrapped OCaml/Lwt exception
val protect :
?on_error:(error trace -> 'a tzresult Lwt.t) ->
?canceler:Lwt_canceler.t ->
(unit -> 'a tzresult Lwt.t) ->
'a tzresult Lwt.tprotect 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
val with_timeout :
?canceler:Lwt_canceler.t ->
unit Lwt.t ->
(Lwt_canceler.t -> 'a tzresult Lwt.t) ->
'a tzresult Lwt.t