package octez-libs
Tree
provides immutable, in-memory partial mirror of the context, with lazy reads and delayed writes. The trees are Merkle trees that carry the same hash as the part of the context they mirror.
Trees are immutable and non-persistent (they disappear if the host crash), held in memory for efficiency, where reads are done lazily and writes are done only when needed, e.g. on Context.commit
. If a key is modified twice, only the last value will be written to disk on commit.
include VIEW with type t := tree and type tree := tree
Getters
mem t k
is an Lwt promise that resolves to true
iff k
is bound to a value in t
.
find t k
is an Lwt promise that resolves to Some v
if k
is bound to the value v
in t
and None
otherwise.
list t key
is the list of files and sub-nodes stored under k
in t
. The result order is not specified but is stable.
offset
and length
are used for pagination.
length t key
is an Lwt promise that resolves to the number of files and sub-nodes stored under k
in t
.
It is equivalent to let+ l = list t k in List.length l
but has a constant-time complexity.
Setters
add t k v
is an Lwt promise that resolves to c
such that:
k
is bound tov
inc
;- and
c
is similar tot
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.
remove t k v
is an Lwt promise that resolves to c
such that:
k
is unbound inc
;- and
c
is similar tot
otherwise.
Folding
val fold :
?depth:depth ->
tree ->
key ->
order:[ `Sorted | `Undefined ] ->
init:'a ->
f:(key -> tree -> 'a -> 'a Lwt.t) ->
'a Lwt.t
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 values of depth exactlyd
.Lt d
folds over nodes and values of depth strictly less thand
.Le d
folds over nodes and values of depth less than or equal tod
.Gt d
folds over nodes and values of depth strictly more thand
.Ge d
folds over nodes and values of depth more than or equal tod
.
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
.
Configuration
val is_empty : tree -> bool
is_empty t
is true iff t
is empty _
.
to_value t
is an Lwt promise that resolves to Some v
if t
is a leaf tree and None
otherwise. It is equivalent to find t
[]
.
of_value _ v
is an Lwt promise that resolves to the leaf tree v
. Is is equivalent to add (empty _) [] v
.
val hash : tree -> Tezos_base.TzPervasives.Context_hash.t
hash t
is t
's Merkle hash.
Caches
val clear : ?depth:int -> tree -> unit
clear ?depth t
clears all caches in the tree t
for subtrees with a depth higher than depth
. If depth
is not set, all of the subtrees are cleared.