Module Tezos_base__TzPervasives

include module type of sig ... end
module Bits : sig ... end
module Bloomer : sig ... end
module Bounded_heap : sig ... end
module Circular_buffer : sig ... end
module Compare : sig ... end
module FallbackArray : sig ... end
module FunctionalArray : sig ... end
module Lwt_dropbox : sig ... end
module Lwt_idle_waiter : sig ... end
module Lwt_pipe : sig ... end
module Lwt_utils : sig ... end
module Memory : sig ... end
module ReadOnlyArray : sig ... end
module Tag : sig ... end
module TzEndian : sig ... end
module TzFilename : sig ... end
module TzList : sig ... end
module TzString : sig ... end
module Utils : sig ... end
module Error_monad : module type of sig ... end
include module type of Tezos_rpc
module RPC_answer : sig ... end
module RPC_arg : sig ... end
module RPC_context : sig ... end
module RPC_description : sig ... end
module RPC_directory : sig ... end
module RPC_encoding : sig ... end
module RPC_error : sig ... end
module RPC_path : sig ... end
module RPC_query : sig ... end
module RPC_service : sig ... end
include module type of Tezos_clic
module Clic : sig ... end
include module type of Tezos_crypto
module Base58 : sig ... end
module Blake2B : sig ... end
module Block_hash : sig ... end
module Block_metadata_hash : sig ... end
module Chain_id : sig ... end
module Context_hash : sig ... end
module Crypto_box : sig ... end
module Ed25519 : sig ... end
module Hacl : sig ... end
module Helpers : sig ... end
module Operation_hash : sig ... end
module Operation_list_hash : sig ... end
module Operation_list_list_hash : sig ... end
module Operation_metadata_hash : sig ... end
module Operation_metadata_list_hash : sig ... end
module Operation_metadata_list_list_hash : sig ... end
module P256 : sig ... end
module Protocol_hash : sig ... end
module Pvss : sig ... end
module Pvss_secp256k1 : sig ... end
module Rand : sig ... end
module S : sig ... end
module Secp256k1 : sig ... end
module Secp256k1_group : sig ... end
module Signature : sig ... end
module Timelock : sig ... end
module Znz : sig ... end
module Zplus : sig ... end
module Data_encoding = Data_encoding
include module type of Tezos_error_monad.TzLwtreslib
include module type of sig ... end
module Monad : sig ... end
module Hashtbl : sig ... end
module List : sig ... end
module Map : sig ... end
module Option : sig ... end
module Result : sig ... end
module Seq : sig ... end
module Seq_e : sig ... end
module Seq_s : sig ... end
module Seq_es : sig ... end
module Set : sig ... end
module Unit : sig ... end
module WithExceptions : sig ... end
module List : sig ... end
module String : sig ... end
module Time = Tezos_base.Time
module Fitness = Tezos_base.Fitness
module User_activated = Tezos_base.User_activated
module Block_header = Tezos_base.Block_header
module Genesis = Tezos_base.Genesis
module Operation = Tezos_base.Operation
module Protocol = Tezos_base.Protocol
module Test_chain_status = Tezos_base.Test_chain_status
module Block_locator = Tezos_base.Block_locator
module Mempool = Tezos_base.Mempool
module P2p_addr = Tezos_base.P2p_addr
module P2p_identity = Tezos_base.P2p_identity
module P2p_peer = Tezos_base.P2p_peer
module P2p_point = Tezos_base.P2p_point
module P2p_connection = Tezos_base.P2p_connection
module P2p_stat = Tezos_base.P2p_stat
module P2p_version = Tezos_base.P2p_version
module P2p_rejection = Tezos_base.P2p_rejection
module Distributed_db_version = Tezos_base.Distributed_db_version
module Network_version = Tezos_base.Network_version
include module type of Utils.Infix
val (--) : int -> int -> int list

Sequence: i--j is the sequence i;i+1;...;j-1;j

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 = ..
include Tezos_error_monad.Sig.CORE with type error := error
type error
val error_encoding : error Data_encoding.t
val pp : Stdlib.Format.formatter -> error -> unit
include Tezos_error_monad.Sig.EXT with type error := error
type error = ..
val 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) -> 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 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) -> unit

Same 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_category

Classify an error using the registered kinds

type error += Unclassified of string

Catch all error when 'serializing' an error.

type error += Unregistered_error of Data_encoding.json
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 : 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 -> unit
val find_info_of_error : error -> error_info

find_info_of_error e retrieves the `error_info` associated with the given error `e`.

raises [Invalid_argument]

if the error is a wrapped error from another monad

raises [Not_found]

if the error's constructor has not been registered

val get_registered_errors : unit -> error_info list

Retrieves information of registered errors

include Tezos_error_monad.Sig.WITH_WRAPPED with type error := error
type error
module type Wrapped_error_monad = sig ... end
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.

type 'error trace = 'error TzTrace.trace
include Tezos_lwt_result_stdlib.Lwtreslib.TRACED_MONAD with type 'error trace := 'error TzTrace.trace

Most of it is defined in the non-traced monad. The rest is trace-specific, occasionally shadowing.

include Bare_sigs.Monad.S

The Lwt monad: for concurrency

module Lwt : module type of sig ... end
val (>>=) : 'a Lwt.t -> ('a -> 'b Lwt.t) -> 'b Lwt.t

(>>=) is the monad-global infix alias for Lwt.bind.

val (>|=) : 'a Lwt.t -> ('a -> 'b) -> 'b Lwt.t

(>|=) is the monad-global infix alias for Lwt.map.

The (generic) Result monad: for success/failure

val ok : 'a -> ('a'e) Stdlib.result

ok is the monad-global alias for Result.return.

val error : 'e -> ('a'e) Stdlib.result

error is the monad-global alias for Result.fail.

val (>>?) : ('a'e) Stdlib.result -> ('a -> ('b'e) Stdlib.result) -> ('b'e) Stdlib.result

(>>?) is the monad-global infix alias for Result.bind.

val (>|?) : ('a'e) Stdlib.result -> ('a -> 'b) -> ('b'e) Stdlib.result

(>|?) is the monad-global infix alias for Result.map.

The combined Lwt+Result monad: for concurrent successes/failures

module LwtResult : sig ... end
val return : 'a -> ('a'e) Stdlib.result Lwt.t

return is the monad-global alias for LwtResult.return.

val fail : 'e -> ('a'e) Stdlib.result Lwt.t

fail is the monad-global alias for LwtResult.fail.

val (>>=?) : ('a'e) Stdlib.result Lwt.t -> ('a -> ('b'e) Stdlib.result Lwt.t) -> ('b'e) Stdlib.result Lwt.t

(>>=?) is the monad-global infix alias for LwtResult.bind.

val (>|=?) : ('a'e) Stdlib.result Lwt.t -> ('a -> 'b) -> ('b'e) Stdlib.result Lwt.t

(>|=?) is the monad-global infix alias for LwtResult.map.

Mixing operators

These are helpers to "go from one monad into another".

val (>>?=) : ('a'e) Stdlib.result -> ('a -> ('b'e) Stdlib.result Lwt.t) -> ('b'e) Stdlib.result Lwt.t
val (>|?=) : ('a'e) Stdlib.result -> ('a -> 'b Lwt.t) -> ('b'e) Stdlib.result Lwt.t

Joins

These functions handle lists (or tuples) of in-monad value.

val join_p : unit Lwt.t list -> unit Lwt.t

join_p is the joining of concurrent unit values (it is Lwt.join).

val all_p : 'a Lwt.t list -> 'a list Lwt.t

all_p is the joining of concurrent non-unit values (it is Lwt.all).

val both_p : 'a Lwt.t -> 'b Lwt.t -> ('a * 'b) Lwt.t

both_p is the joining of two concurrent non-unit values (it is Lwt.both).

val join_e : (unit, 'e) Stdlib.result list -> (unit, 'e list) Stdlib.result

join_e is the joining of success/failure unit values.

val all_e : ('a'e) Stdlib.result list -> ('a list'e list) Stdlib.result

all_e is the joining of success/failure non-unit values.

val both_e : ('a'e) Stdlib.result -> ('b'e) Stdlib.result -> ('a * 'b'e list) Stdlib.result

both_e is the joining of two success/failure non-unit values.

val join_ep : (unit, 'e) Stdlib.result Lwt.t list -> (unit, 'e list) Stdlib.result Lwt.t

join_ep is the joining of concurrent success/failure unit values.

val all_ep : ('a'e) Stdlib.result Lwt.t list -> ('a list'e list) Stdlib.result Lwt.t

all_ep is the joining of concurrent success/failure non-unit values.

val both_ep : ('a'e) Stdlib.result Lwt.t -> ('b'e) Stdlib.result Lwt.t -> ('a * 'b'e list) Stdlib.result Lwt.t

both_ep is the joining of two concurrent success/failure non-unit values.

type 'error trace

'error trace is intended to be substituted by a type provided by a Trace module (with type 'error trace := 'error Trace.trace)

module TracedResult : sig ... end
val error_trace : 'error -> ('a'error trace) Stdlib.result

error_trace e is the monad-global alias for TracedResult.fail e.

module LwtTracedResult : sig ... end
val fail_trace : 'error -> ('a'error trace) Stdlib.result Lwt.t

fail_trace e is the monad-global alias for LwtTracedResult.fail e.

val join_e : (unit, 'error trace) Stdlib.result list -> (unit, 'error trace) Stdlib.result

Joins

Joins are similar to the non-traced monad's functions of the same names. The difference is that failures that are joined together are grouped in a traced (using Trace.conp/Trace.conp_list) rather than returned as a list.

val all_e : ('a'error trace) Stdlib.result list -> ('a list'error trace) Stdlib.result
val both_e : ('a'error trace) Stdlib.result -> ('b'error trace) Stdlib.result -> ('a * 'b'error trace) Stdlib.result
val join_ep : (unit, 'error trace) Stdlib.result Lwt.t list -> (unit, 'error trace) Stdlib.result Lwt.t
val all_ep : ('a'error trace) Stdlib.result Lwt.t list -> ('a list'error trace) Stdlib.result Lwt.t
val both_ep : ('a'error trace) Stdlib.result Lwt.t -> ('b'error trace) Stdlib.result Lwt.t -> ('a * 'b'error trace) Stdlib.result Lwt.t
include Tezos_error_monad.Sig.MONAD_EXT with type error := error and type 'error trace := 'error TzTrace.trace
type error

for substitution

type 'error trace

for substitution

type tztrace = error trace
type 'a tzresult = ('atztrace) Stdlib.result
val classify_errors : tztrace -> Tezos_error_monad.Sig.error_category
val return : 'a -> ('a'e) Stdlib.result Lwt.t
val return_unit : (unit, 'e) Stdlib.result Lwt.t
val return_none : ('a option'e) Stdlib.result Lwt.t
val return_some : 'a -> ('a option'e) Stdlib.result Lwt.t
val return_nil : ('a list'e) Stdlib.result Lwt.t
val return_true : (bool, 'e) Stdlib.result Lwt.t
val return_false : (bool, 'e) Stdlib.result Lwt.t
val fail : 'error -> ('a'error trace) Stdlib.result Lwt.t

more defaulting to trace

val error : 'error -> ('a'error trace) Stdlib.result
val pp_print_error : Stdlib.Format.formatter -> error trace -> unit
val pp_print_error_first : Stdlib.Format.formatter -> error trace -> unit

Pretty prints a trace as the message of its first error

val trace_encoding : error trace 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 trace) Stdlib.result -> ('a'err trace) Stdlib.result

Enrich an error report (or do nothing on a successful result) manually

val trace : 'err -> ('b'err trace) Stdlib.result Lwt.t -> ('b'err trace) Stdlib.result Lwt.t

Automatically enrich error reporting on stack rewind

val record_trace_eval : (unit -> ('err'err trace) Stdlib.result) -> ('a'err trace) Stdlib.result -> ('a'err trace) Stdlib.result

Same as record_trace, for unevaluated error

val trace_eval : (unit -> ('err'err trace) Stdlib.result Lwt.t) -> ('b'err trace) Stdlib.result Lwt.t -> ('b'err trace) Stdlib.result Lwt.t

Same as trace, for unevaluated Lwt error

val error_unless : bool -> 'err -> (unit, 'err trace) Stdlib.result

Error on failed assertion

val error_when : bool -> 'err -> (unit, 'err trace) Stdlib.result
val fail_unless : bool -> 'err -> (unit, 'err trace) Stdlib.result Lwt.t

Erroneous return on failed assertion

val fail_when : bool -> 'err -> (unit, 'err trace) Stdlib.result Lwt.t
val unless : bool -> (unit -> (unit, 'trace) Stdlib.result Lwt.t) -> (unit, 'trace) Stdlib.result Lwt.t
val when_ : bool -> (unit -> (unit, 'trace) Stdlib.result Lwt.t) -> (unit, 'trace) Stdlib.result Lwt.t
val dont_wait : (unit -> (unit, 'trace) Stdlib.result Lwt.t) -> ('trace -> unit) -> (exn -> unit) -> unit

Wrapper around Lwt_utils.dont_wait

Exception-Error bridge

val generic_error : ('a, Stdlib.Format.formatter, unit, 'b tzresult) Stdlib.format4 -> 'a

generic_error is for generic failure within the Result monad. You should use this function rarely: only when there isn't a more specific error.

The traced error carried in the returned value is unspecified. It is not meant to be recovered from. The error message includes the one passed as argument. Tracking the origin of these errors is generally more difficult than tracking a more specialised error.

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

val failwith : ('a, Stdlib.Format.formatter, unit, 'b tzresult Lwt.t) Stdlib.format4 -> 'a

failwith is like generic_error but for the LwtResult-monad. The same usage notes apply.

val error_exn : exn -> 'a tzresult

error_exn exc wraps the exception exc within an (unspecified) error within a trace within a result. 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_exn exc

error_exn is named after error which is the function that fails within the TracedResult monad. If you need a lower-level function that constructs the error trace but doesn't wrap it in a result, you can use error_of_exn.

val error_of_exn : exn -> error trace

error_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)

error_of_exn converts (by wrapping) an exception into a traced error. If you intend to place this value in an Error construct, you can use error_exn instead.

val tzresult_of_exn_result : ('a, exn) Stdlib.result -> 'a tzresult

tzresult_of_exn_result r wraps the payload construction of the Error constructor of a result into a tzresult. This is intended for use when interacting with code that uses exceptions wrapped in a result. E.g.,

let p : int Lwt.t = … in
Lwt_result.catch p >|= tzresult_of_exn_result

Exception traces

The following functions allow you to enrich existing traces with wrapped exceptions.

val record_trace_exn : exn -> 'a tzresult -> 'a tzresult

record_trace_exn exc r is record_trace (error_of_exn exc) r

val trace_exn : exn -> 'b tzresult Lwt.t -> 'b tzresult Lwt.t

trace_exn exc r is trace (error_of_exn exc) r

val generic_trace : ('a, Stdlib.Format.formatter, unit, ('berror trace) Stdlib.result Lwt.t -> ('berror trace) Stdlib.result Lwt.t) Stdlib.format4 -> 'a

generic_trace … r is r where the trace (if any) is enriched with generic_error ….

val pp_exn : Stdlib.Format.formatter -> exn -> unit
val failure : ('a, Stdlib.Format.formatter, unit, error) Stdlib.format4 -> 'a

failure … is like generic_error … but the error isn't wrapped in a trace in a result.

type error += Exn of exn

Wrapped OCaml/Lwt exception

type error += Canceled
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.

val catch_e : ?⁠catch_only:(exn -> bool) -> (unit -> 'a tzresult) -> 'a tzresult

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.

val catch_f : ?⁠catch_only:(exn -> bool) -> (unit -> 'a) -> (exn -> error) -> 'a tzresult

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 catch_s : ?⁠catch_only:(exn -> bool) -> (unit -> 'a Lwt.t) -> 'a tzresult Lwt.t

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.

val catch_es : ?⁠catch_only:(exn -> bool) -> (unit -> 'a tzresult Lwt.t) -> 'a tzresult Lwt.t

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.

type error += Timeout
val with_timeout : ?⁠canceler:Lwt_canceler.t -> unit Lwt.t -> (Lwt_canceler.t -> 'a tzresult Lwt.t) -> 'a tzresult Lwt.t
module Internal_event = Tezos_event_logging.Internal_event
module Filename : sig ... end