package octez-libs
include module type of struct include Tezos_stdlib end
module Bits = Tezos_stdlib.Bits
module Bloomer = Tezos_stdlib.Bloomer
module Bounded_heap = Tezos_stdlib.Bounded_heap
module Circular_buffer = Tezos_stdlib.Circular_buffer
module Compare = Tezos_stdlib.Compare
module FallbackArray = Tezos_stdlib.FallbackArray
module FunctionalArray = Tezos_stdlib.FunctionalArray
module Hash_queue = Tezos_stdlib.Hash_queue
module Hex = Tezos_stdlib.Hex
module Lwt_dropbox = Tezos_stdlib.Lwt_dropbox
module Lwt_idle_waiter = Tezos_stdlib.Lwt_idle_waiter
module Lwt_pipe = Tezos_stdlib.Lwt_pipe
module Lwt_utils = Tezos_stdlib.Lwt_utils
module Memory = Tezos_stdlib.Memory
module Tag = Tezos_stdlib.Tag
module TzBytes = Tezos_stdlib.TzBytes
module TzEndian = Tezos_stdlib.TzEndian
module TzFilename = Tezos_stdlib.TzFilename
module TzList = Tezos_stdlib.TzList
module TzString = Tezos_stdlib.TzString
module Utils = Tezos_stdlib.Utils
module Error_monad = Tezos_error_monad.Error_monad
module Error_monad_legacy = Tezos_error_monad_legacy.Error_monad
module Data_encoding = Data_encoding
module Hashtbl = Tezos_error_monad.TzLwtreslib.Hashtbl
The following modules are part of TzLwtreslib
. We just remove
module Map = Tezos_error_monad.TzLwtreslib.Map
module Option = Tezos_error_monad.TzLwtreslib.Option
module Result = Tezos_error_monad.TzLwtreslib.Result
module Seq = Tezos_error_monad.TzLwtreslib.Seq
module Seq_e = Tezos_error_monad.TzLwtreslib.Seq_e
module Seq_s = Tezos_error_monad.TzLwtreslib.Seq_s
module Seq_es = Tezos_error_monad.TzLwtreslib.Seq_es
module Set = Tezos_error_monad.TzLwtreslib.Set
module Unit = Tezos_error_monad.TzLwtreslib.Unit
module WithExceptions = Tezos_error_monad.TzLwtreslib.WithExceptions
module List : sig ... end
module String : sig ... end
module Bytes : sig ... end
module Time = Time
module Fitness = Fitness
module User_activated = User_activated
module Block_header = Block_header
module Genesis = Genesis
module Operation = Operation
module Protocol = Protocol
module Test_chain_status = Test_chain_status
module Block_locator = Block_locator
module Mempool = Mempool
module P2p_addr = P2p_addr
module P2p_identity = P2p_identity
module P2p_peer = P2p_peer
module P2p_point = P2p_point
module P2p_connection = P2p_connection
module P2p_stat = P2p_stat
module P2p_version = P2p_version
module P2p_rejection = P2p_rejection
module P2p_params = P2p_params
module Distributed_db_version = Distributed_db_version
module Network_version = Network_version
module Block_hash = Tezos_crypto.Hashed.Block_hash
module Block_metadata_hash = Tezos_crypto.Hashed.Block_metadata_hash
module Chain_id = Tezos_crypto.Hashed.Chain_id
module Context_hash = Tezos_crypto.Hashed.Context_hash
module Operation_hash = Tezos_crypto.Hashed.Operation_hash
module Operation_list_hash = Tezos_crypto.Hashed.Operation_list_hash
module Operation_list_list_hash = Tezos_crypto.Hashed.Operation_list_list_hash
module Operation_metadata_hash = Tezos_crypto.Hashed.Operation_metadata_hash
module Operation_metadata_list_hash =
Tezos_crypto.Hashed.Operation_metadata_list_hash
module Operation_metadata_list_list_hash =
Tezos_crypto.Hashed.Operation_metadata_list_list_hash
module Protocol_hash = Tezos_crypto.Hashed.Protocol_hash
module Signature = Tezos_crypto.Signature
module Skip_list = Skip_list
include module type of Utils.Infix
include module type of Tezos_error_monad.Error_monad
type error_category = [
| `Branch
(*Errors that may not happen in another context
*)| `Temporary
(*Errors that may not happen in a later context
*)| `Permanent
(*Errors that will happen no matter the context
*)
]
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
Assembling the different components of the error monad.
type error = Tezos_error_monad.TzCore.error = ..
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
.
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.
CORE
: encoding and pretty-printing for errors
include Tezos_error_monad.Sig.CORE
with type error := error
and type error_category := error_category
val string_of_category : error_category -> string
val error_encoding : error Data_encoding.t
The encoding for errors.
Note that this encoding has a few peculiarities, some of which may impact your code. These peculiarities are due to the type error
being an extensible variant.
Because the error
type is an extensible variant, you must register an encoding for each error constructor you add to error
. This is done via register_error_kind
.
Because the error
type is an extensible variant, with dynamically registered errors (see peculiarity above), there are no tags associated with each error. This does not affect the JSON encoding, but it does impose restrictions on the binary encoding. The chosen workaround is to encode errors as JSON and to encode the JSON to binary form. As a result, errors can be somewhat large in binary: they include field names and such.
Because the error
type is an extensible variant, with dynamically registered errors (see peculiarity above), the encoding must be recomputed when a new error is registered. This is achieved by the means of a Data_encoding.delayed
combinator: the encoding is recomputed on-demand. There is a caching mechanism so that, in the case where no new errors have been registered since the last use, the last result is used.
This last peculiarity imposes a limit on the use of error_encoding
itself. Specifically, it is invalid to use error_encoding
inside the ~json
argument of a Data_encoding.splitted
. This is because splitted
evaluates the delayed
combinator once-and-for-all to produce a json encoding. (Note that the following data-encoding combinators use splitted
internally: Data_encoding.Compact.make
, Data_encoding.assoc
, and Data_encoding.lazy_encoding
. As a result, it is invalid to use error_encoding
within the arguments of these combinators as well.)
val pp : Format.formatter -> error -> unit
val register_error_kind :
error_category ->
id:string ->
title:string ->
description:string ->
?pp:(Format.formatter -> 'err -> unit) ->
'err Data_encoding.t ->
(error -> 'err option) ->
('err -> error) ->
unit
The 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 classify_error : error -> Tezos_error_monad.Error_classification.t
Classify an error using the registered kinds
Catch all error when 'serializing' an error.
Catch all error when 'deserializing' an error.
val json_of_error : error -> Data_encoding.json
An error serializer
val error_of_json : Data_encoding.json -> error
Error documentation
type error_info = {
category : error_category;
id : string;
title : string;
description : string;
schema : Data_encoding.json_schema;
}
Error information
val pp_info : Format.formatter -> error_info -> unit
val find_info_of_error : error -> error_info
find_info_of_error e
retrieves the `error_info` associated with the given error `e`.
val get_registered_errors : unit -> error_info list
Retrieves information of registered errors
WITH_WRAPPED
: wrapping of errors from other instantiations within this one. Specifically, this is used to wrap errors of the economic protocol (e.g., operation is invalid) within the errors of the shell (e.g., failed to validate protocol data).
Functions from this module should only be used within the environment.
include Tezos_error_monad.Sig.WITH_WRAPPED with type error := error
module type Wrapped_error_monad = sig ... end
The purpose of this module is to wrap a specific error monad E
into a more general error monad Eg
.
val register_wrapped_error_kind :
(module Wrapped_error_monad) ->
id:string ->
title:string ->
description:string ->
unit
Same 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.Sig.TRACE with type 'error trace = 'error list
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).
type 'error trace = 'error TzTrace.trace
TzMonad
: the Tezos-specific monad part of the Error_monad
. It includes
- syntax modules
- consistent defaults,
- some tracing helpers,
- some other misc helpers.
include Tezos_error_monad.Monad_maker.S
with type error := Tezos_error_monad.TzCore.error
and type 'error trace := 'error TzTrace.trace
type tztrace = Tezos_error_monad.TzCore.error TzTrace.trace
module Lwt_syntax :
module type of Tezos_error_monad.TzLwtreslib.Monad.Lwt_syntax
module Result_syntax : sig ... end
module Lwt_result_syntax : sig ... end
val classify_trace : tztrace -> Tezos_error_monad.Error_classification.t
val pp_print_trace : Format.formatter -> tztrace -> unit
val pp_print_top_error_of_trace : Format.formatter -> tztrace -> unit
Pretty-prints the top error of a trace
val trace_encoding : tztrace Data_encoding.t
val result_encoding : 'a Data_encoding.t -> 'a tzresult Data_encoding.t
A serializer for result of a given type
val record_trace :
'err ->
('a, 'err TzTrace.trace) result ->
('a, 'err TzTrace.trace) result
record_trace err res
is either res
if res
is Ok _
, or it is Error (Trace.cons err tr)
if res
is Error tr
.
In other words, record_trace err res
enriches the trace that is carried by res
(if it is carrying a trace) with the error err
. It leaves res
untouched if res
is not carrying a trace.
You can use this to add high-level information to potential low-level errors. E.g.,
record_trace
Failure_to_load_config
(load_data_from_file config_encoding config_file_name)
Note that record_trace
takes a fully evaluated error err
as argument. It means that, whatever the value of the result res
, the error err
is evaluated. This is not an issue if the error is a simple expression (a literal or a constructor with simple parameters). However, for any expression that is more complex (e.g., one that calls a function) you should prefer record_trace_eval
.
val trace :
'err ->
('b, 'err TzTrace.trace) result Lwt.t ->
('b, 'err TzTrace.trace) result Lwt.t
trace
is identical to record_trace
but applies to a promise. More formally, trace err p
is a promise that resolves to Ok v
if p
resolves to Ok v
, or it resolves to Error (Trace.cons err tr)
if res
resolves to Error tr
.
In other words, trace err p
enriches the trace that p
resolves to (if it does resolve to a trace) with the error err
. It leaves the value that p
resolves to untouched if it is not a trace.
You can use this to add high-level information to potential low-level errors.
Note that, like record_trace
, trace
takes a fully evaluated error as argument. For a similar reason as explained there, you should only use trace
with simple expressions (literal or constructor with simple parameters) and prefer trace_eval
for any other expression (such as ones that include functions calls).
val record_trace_eval :
(unit -> 'err) ->
('a, 'err TzTrace.trace) result ->
('a, 'err TzTrace.trace) result
record_trace_eval
is identical to record_trace
except that the error that enriches the trace is wrapped in a function that is evaluated only if it is needed. More formally record_trace_eval mkerr res
is res
if res
is Ok _
, or it is Error (Trace.cons (mkerr ()) tr)
if res
is Error tr
.
You can achieve the same effect by hand with
match res with
| Ok _ -> res
| Error tr -> Error (Trace.cons (mkerr ()) tr)
Prefer record_trace_eval
over record_trace
when the enriching error is expensive to compute or heavy to allocate.
val trace_eval :
(unit -> 'err) ->
('b, 'err TzTrace.trace) result Lwt.t ->
('b, 'err TzTrace.trace) result Lwt.t
trace_eval
is identical to trace
except that the error that enriches the trace is wrapped in a function that is evaluated only if and when it is needed. More formally trace_eval mkerr p
is a promise that resolves to Ok v
if p
resolves to Ok v
, or it resolves to Error (Trace.cons err tr)
if p
resolves to Error tr
and then mkerr
()
resolves to err
.
You can achieve the same effect by hand with
p >>= function
| Ok _ -> p
| Error tr ->
mkerr () >>= fun err ->
Lwt.return (Error (Trace.cons err tr))
Note that the evaluation of the error can be arbitrarily delayed. Avoid using references and other mutable values in the function mkerr
.
Prefer trace_eval
over trace
when the enriching error is expensive to compute or heavy to allocate or when evaluating it requires the use of Lwt.
val error_unless : bool -> 'err -> (unit, 'err TzTrace.trace) result
error_unless flag err
is Ok ()
if b
is true
, it is Error (Trace.make err)
otherwise.
val error_when : bool -> 'err -> (unit, 'err TzTrace.trace) result
error_when flag err
is Error (Trace.make err)
if b
is true
, it is Ok ()
otherwise.
val fail_unless : bool -> 'err -> (unit, 'err TzTrace.trace) result Lwt.t
fail_unless flag err
is Lwt.return @@ Ok ()
if b
is true
, it is Lwt.return @@ Error (Trace.make err)
otherwise.
val fail_when : bool -> 'err -> (unit, 'err TzTrace.trace) result Lwt.t
fail_when flag err
is Lwt.return @@ Error (Trace.make err)
if b
is true
, it is Lwt.return @@ Ok ()
otherwise.
unless b f
is f ()
if b
is false
and it is a promise already resolved to Ok ()
otherwise.
You can use unless
to avoid having to write an if
statement that you then need to populate entirely to satisfy the type-checker. E.g, you can write unless b f
instead of if not b then f () else return_unit
.
when_ b f
is f ()
if b
is true
and it is a promise already resolved to Ok ()
otherwise.
You can use when_
to avoid having to write an if
statement that you then need to populate entirely to satisfy the type-checker. E.g, you can write when_ b f
instead of if b then f () else return_unit
.
Exception-Error bridge
This part of the interface groups functions that are used to interact with code that raises exceptions. Typically, you should be using these functions when calling into a library that raises exceptions.
Remember that the keyword error
is for failure within the Result
monad (or, more specifically, the TracedResult
monad) whilst fail
is for failure within the LwtResult
monad (or, more specifically, the LwtTracedResult
monad).
Failing: to error out and to fail
This sub-part of the interface groups functions that fail (either in the TracedResult
monad or the LwtTracedResult
monad) whilst carrying information provided as argument. When reading this sub-part you should read error
and fail
as verbs. E.g., error_with_exn
errors out and carries a provided exception. The next sub-part will group noun-like, declarative functions.
val error_with : ('a, Format.formatter, unit, 'b tzresult) format4 -> 'a
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.
val failwith : ('a, Format.formatter, unit, 'b tzresult Lwt.t) format4 -> 'a
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.
val error_with_exn : exn -> 'a tzresult
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 -> Lwt.reraise exn (* re-raise by default *))
Whilst it is useful in specific places, it is generally better to use a dedicated error.
Conversions: an exception, an error, a trace, a result
This sub-part of the interface groups declarative functions that convert between different styles of error (exceptions, errors, traces, results). By themselves these functions have no effect within the Result or LwtResult monad, and they are generally used along with constructors or combinators.
val error_of_exn : exn -> 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.
val error_of_fmt : ('a, Format.formatter, unit, error) format4 -> 'a
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)
Standard errors
Wrapped OCaml/Lwt exception
Cancelation
Catching exceptions
val protect :
?on_error:(error trace -> 'a tzresult Lwt.t) ->
?canceler:Lwt_canceler.t ->
(unit -> 'a tzresult Lwt.t) ->
'a tzresult Lwt.t
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
val catch : ?catch_only:(exn -> bool) -> (unit -> 'a) -> 'a tzresult
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_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.
val protect_result :
?canceler:Lwt_canceler.t ->
(unit -> 'a Lwt.t) ->
('a, exn) result Lwt.t
protect_result
is similar to protect
except that any non runtime exception raised by Lwt.catch
is wrapped under an Error
value.
Misc
val with_timeout :
?canceler:Lwt_canceler.t ->
unit Lwt.t ->
(Lwt_canceler.t -> 'a tzresult Lwt.t) ->
'a tzresult Lwt.t
module Option_syntax =
Tezos_lwt_result_stdlib.Lwtreslib.Bare.Monad.Option_syntax
module Lwt_option_syntax =
Tezos_lwt_result_stdlib.Lwtreslib.Bare.Monad.Lwt_option_syntax
module Internal_event = Tezos_event_logging.Internal_event
module Filename : sig ... end
module Bounded = Bounded
module Empty : sig ... end
The main purpose of this module is to be used with parametric types such as ('a, Empty.t) result
. Such type is actually isomorphic to 'a
(see get_ok
function). This is useful if a module signature expects a generic ('a,'b) result
type, but for some instantiation, 'b
is actually empty. Here is a small example how such module can be used:
module Profiler = Profiler
module type PRINTABLE = sig ... end
module type COMPARABLE = Compare.S
module type ENCODABLE = sig ... end