Module Irmin_context.Tree

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 Mavryk_context_sigs.Context.VIEW with type t := tree and type tree := tree with type key := string list with type value := bytes

Getters

val mem : tree -> string list -> bool Lwt.t

mem t k is an Lwt promise that resolves to true iff k is bound to a value in t.

val mem_tree : tree -> string list -> bool Lwt.t

mem_tree t k is like mem but for trees.

val find : tree -> string list -> bytes option Lwt.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.

val find_tree : tree -> string list -> tree option Lwt.t

find_tree t k is like find but for trees.

val list : tree -> ?offset:int -> ?length:int -> string list -> (string * tree) list Lwt.t

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.

val length : tree -> string list -> int Lwt.t

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

val add : tree -> string list -> bytes -> tree Lwt.t

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.

val add_tree : tree -> string list -> tree -> tree Lwt.t

add_tree is like add but for trees.

val remove : tree -> string list -> tree Lwt.t

remove t k v is an Lwt promise that resolves to c such that:

  • k is unbound in c;
  • and c is similar to t otherwise.

Folding

val fold : ?depth:Mavryk_context_sigs.Context.depth -> tree -> string list -> order:[ `Sorted | `Undefined ] -> init:'a -> f:(string list -> 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 exactly d.
  • Lt d folds over nodes and values of depth strictly less than d.
  • Le d folds over nodes and values of depth less than or equal to d.
  • Gt d folds over nodes and values of depth strictly more than d.
  • Ge d folds over nodes and values 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.

Configuration

config t is t's hash configuration.

val empty : rw -> tree

empty _ is the empty tree.

val is_empty : tree -> bool

is_empty t is true iff t is empty _.

kind t is t's kind. It's either a tree node or a leaf value.

val to_value : tree -> bytes option Lwt.t

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 [].

val of_value : rw -> bytes -> tree Lwt.t

of_value _ v is an Lwt promise that resolves to the leaf tree v. Is is equivalent to add (empty _) [] v.

hash t is t's Merkle hash.

val equal : tree -> tree -> bool

equal x y is true iff x and y have the same 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.