Abstract type of a cache. A cache is made of subcaches. Each subcache has its own size limit. The limit of its subcache is called a layout and can be initialized via the set_cache_layout function.
add t k v is an Lwt promise that resolves to c such that:
k is bound to v in c;
and c is similar to t otherwise.
If k was already bound in t to a value that is physically equal to v, the result of the function is a promise that resolves to t. Otherwise, the previous binding of k in t disappears.
fold ?depth t root ~order ~init ~f recursively folds over the trees and values of t. The f callbacks are called with a key relative to root. f is never called with an empty key for values; i.e., folding over a value is a no-op.
The depth is 0-indexed. If depth is set (by default it is not), then f is only called when the conditions described by the parameter is true:
Eq d folds over nodes and contents of depth exactly d.
Lt d folds over nodes and contents of depth strictly less than d.
Le d folds over nodes and contents of depth less than or equal to d.
Gt d folds over nodes and contents of depth strictly more than d.
Ge d folds over nodes and contents of depth more than or equal to d.
If order is `Sorted (the default), the elements are traversed in lexicographic order of their keys. For large nodes, it is memory-consuming, use `Undefined for a more memory efficient fold.
val make :
kind:'akind->impl_name:string ->ctxt:'a->ops:('a, 'b)ops->equality_witness:('a, 'b)equality_witness->t
make kind impl_name ctxt ops equality_witness builds a context value. In this context, the cache is uninitialized: one must call load_cache to obtain a context with a valid cache. Otherwise, the context is not usable for all protocol-level features based on the cache, e.g., smart contract execution.
type cache_key
A key uniquely identifies a cached value in the some subcache.
Abstract type for cached values.
This type is an extensible type since values stored in the cache are heterogeneous. Notice that the cache must be cleared during during protocol stitching because the data constructors of this type are incompatible between two protocols: if there remains values built with a data constructor of an old protocol, the new protocol will be confused to find that some keys it is interesting in have unexploitable values.
A cache is a block-dependent value: to know whether a cache can be reused or recycled in a given block, we need the block that produces it.
During its loading, a cache can be populated in two different ways:
values are computed immediately via the builder and inserted into the cache ; or,
the computation of the values is delayed and will be computed only when such value is required.
The first mode is intended to be used after a rebooting of the node for example. The main benefit being that it does not impact the validation time of a block since the cache's values will be reconstructed beforehand. The second mode is intended to be used for RPCs where reactivity is important: we do not want to recompute the full cache to execute the RPC but only the values which are necessary.
type source_of_cache = [
| `Force_load
(*
Force the cache domain to be reloaded from the context.
*)
| `Load
(*
Load a cache by iterating over the keys of its domain and by building a cached value for each key.
*)
| `Lazy
(*
Same as Load except that cached values are built on demand. This strategy makes load_cache run faster but it may also introduces latencies during block validations.
To avoid any discrepancy between a node that has reloaded its cache and the other nodes of the network, it is recommended to avoid using this function in time-critical components.
RPCs are a typical place where this Lazy loading makes sense, though.
load_cache predecessor ctxt source builder populates the in-memory cache values cached in the current context during the validation of predecessor block. To achieve that, the function uses the strategy described by source, exploiting the builder to create cached values that are not already available in memory.
The builder is assumed to never fail when evaluated on the keys of the cache domain. Indeed, if a key had an associated value in the cache at some point in the past, it should have been a valid key. In other words, the construction of cache should be reproducible. For this reason, an error in builder is fatal.
val reset_cache_cache_hangzhou_issue_do_not_use_except_if_you_know_what_you_are_doing :
unit ->
unit
This function is not documented on purpose. It can be removed if a successor of Hangzhou contains a fix.