Tree provides immutable, in-memory partial mirror of the store, with lazy reads and delayed writes.
Trees are like staging area in Git: they are immutable temporary non-persistent areas (they disappear if the host crash), held in memory for efficiency, where reads are done lazily and writes are done only when needed on commit: if you modify a key twice, only the last change will be written to the store when you commit.
empty () is the empty tree. The empty tree does not have associated backend configuration values, as they can perform in-memory operation, independently of any given backend.
pruned h is a purely in-memory tree with the hash h. Such trees can be used as children of other in-memory tree nodes, for instance in order to compute the hash of the parent, but they cannot be dereferenced.
Any operation that would require loading the contents of a pruned node (e.g. calling find on one of its children) will instead raise a Pruned_hash exception. Attempting to export a tree containing pruned sub-trees to a repository will fail similarly.
val kind : tree->path->[ `Contents | `Node ] optionLwt.t
kind t k is the type of s in t. It could either be a tree node or some file contents. It is None if k is not present in t.
The type for fold's force parameter. `True forces the fold to read the objects of the lazy nodes and contents. `False f is applying f on every lazy node and content value instead.
The type for fold's uniq parameters. `False folds over all the nodes. `True does not recurse on nodes already seen. `Marks m uses the collection of marks m to store the cache of keys: the fold will modify m. This can be used for incremental folds.
For every node n, ui n is a leaf node, call f path n. Otherwise:
Call pre path n. By default pre is the identity;
Recursively call fold on each children.
Call post path n; By default post is the identity.
See force for details about the force parameters. By default it is `True.
See uniq for details about the uniq parameters. By default it is `False.
The fold depth is controlled by the depth parameter.
cache defaults to false, see caching for an explanation of the parameter.
If order is `Sorted (the default), the elements are traversed in lexicographic order of their keys. If `Random state, they are traversed in a random order. For large nodes, these two modes are memory-consuming, use `Undefined for a more memory efficient fold.
Keys in the Irmin store are tagged with the type of the value they reference (either contents or node). In the contents case, the key is paired with corresponding metadata.
key t is the key of tree t in the underlying repository, if it exists. Tree objects that exist entirely in memory (such as those built with of_concrete) have no backend key until they are exported to a repository, and so will return None.
produce r h f runs f on top of a real store r, producing a proof and a result using the initial root hash h.
The trees produced during f's computation will carry the full history of reads. This history will be reset when f is complete so subtrees escaping the scope of f will not cause memory leaks.
Calling produce_proof recursively has an undefined behaviour.
verify p f runs f in checking mode. f is a function that takes a tree as input and returns a new version of the tree and a result. p is a proof, that is a minimal representation of the tree that contains what f should be expecting.
Therefore, contrary to trees found in a storage, the contents of the trees passed to f may not be available. For this reason, looking up a value at some path can now produce three distinct outcomes:
A value v is present in the proof p and returned : find tree path is a promise returning Some v;
path is known to have no value in tree : find tree path is a promise returning None; and
path is known to have a value in tree but p does not provide it because f should not need it: verify returns an error classifying path as an invalid path (see below).
The same semantics apply to all operations on the tree t passed to f and on all operations on the trees built from f.
The generated tree is the tree after f has completed. That tree is disconnected from the backend. It is possible to run operations on it as long as they don't require loading shallowed subtrees, otherwise it would raise Dangling_hash.
The result is Error _ if the proof is rejected:
For tree proofs: when p.before is different from the hash of p.state;
For tree and stream proofs: when p.after is different from the hash of f p.state;
For tree and stream proofs: when f p.state tries to access paths invalid paths in p.state;
For stream proofs: when the proof is not empty once f is done.