package irmin-layers

  1. Overview
  2. Docs

Managing store's trees.

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.

Constructors

val empty : tree

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.

val of_contents : ?metadata:metadata -> contents -> tree

of_contents c is the subtree built from the contents c.

val of_node : node -> tree

of_node n is the subtree built from the node n.

type elt = [
  1. | `Node of node
  2. | `Contents of contents * metadata
]

The type for tree elements.

val v : elt -> tree

General-purpose constructor for trees.

val destruct : tree -> elt

General-purpose destructor for trees.

val kind : tree -> key -> [ `Contents | `Node ] option Lwt.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.

Diffs

val diff : tree -> tree -> (key * (contents * metadata) Irmin.Diff.t) list Lwt.t

diff x y is the difference of contents between x and y.

Manipulating Contents

type 'a or_error = ('a, [ `Dangling_hash of hash ]) result

Operations on lazy nodes can fail if the underlying store does not contain the expected hash.

module Contents : sig ... end

Operations on lazy tree contents.

val mem : tree -> key -> bool Lwt.t

mem t k is true iff k is associated to some contents in t.

val find_all : tree -> key -> (contents * metadata) option Lwt.t

find_all t k is Some (b, m) if k is associated to the contents b and metadata m in t and None if k is not present in t.

val find : tree -> key -> contents option Lwt.t

find is similar to find_all but it discards metadata.

val get_all : tree -> key -> (contents * metadata) Lwt.t

Same as find_all but raise Invalid_arg if k is not present in t.

val list : tree -> ?offset:int -> ?length:int -> key -> (step * 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 get : tree -> key -> contents Lwt.t

Same as get_all but ignore the metadata.

val add : tree -> key -> ?metadata:metadata -> contents -> tree Lwt.t

add t k c is the tree where the key k is bound to the contents c but is similar to t for other bindings.

val update : tree -> key -> ?metadata:metadata -> (contents option -> contents option) -> tree Lwt.t

update t k f is the tree t' that is the same as t for all keys except k, and whose binding for k is determined by f (find t k).

If k refers to an internal node of t, f is called with None to determine the value with which to replace it.

val remove : tree -> key -> tree Lwt.t

remove t k is the tree where k bindings has been removed but is similar to t for other bindings.

Manipulating Subtrees

val mem_tree : tree -> key -> bool Lwt.t

mem_tree t k is false iff find_tree k = None.

val find_tree : tree -> key -> tree option Lwt.t

find_tree t k is Some v if k is associated to v in t. It is None if k is not present in t.

val get_tree : tree -> key -> tree Lwt.t

get_tree t k is v if k is associated to v in t. Raise Invalid_arg if k is not present in t.

val add_tree : tree -> key -> tree -> tree Lwt.t

add_tree t k v is the tree where the key k is bound to the tree v but is similar to t for other bindings

val update_tree : tree -> key -> (tree option -> tree option) -> tree Lwt.t

update_tree t k f is the tree t' that is the same as t for all subtrees except under k, and whose subtree at k is determined by f (find_tree t k).

val merge : tree Irmin.Merge.t

merge is the 3-way merge function for trees.

Folds

type marks

The type for fold marks.

val empty_marks : unit -> marks

empty_marks () is an empty collection of marks.

type 'a force = [
  1. | `True
  2. | `False of key -> 'a -> 'a Lwt.t
  3. | `And_clear
]

The type for fold's force parameter. `True forces the fold to read the objects of the lazy nodes. `False f is applying f on every lazy node instead. `And_clear is like `True but also eagerly empty the Tree caches when traversing sub-nodes.

type uniq = [
  1. | `False
  2. | `True
  3. | `Marks of marks
]

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.

type 'a node_fn = key -> step list -> 'a -> 'a Lwt.t

The type for fold's pre and post parameters.

type depth = [
  1. | `Eq of int
  2. | `Le of int
  3. | `Lt of int
  4. | `Ge of int
  5. | `Gt of int
]

The type for fold depths.

  • Eq d folds over nodes and contents of depth exactly d.
  • Lt d folds over nodes and contents of depth strictly less than d.
  • Gt d folds over nodes and contents of depth strictly more than d.

Le d is Eq d and Lt d. Ge d is Eq d and Gt d.

val depth_t : depth Irmin.Type.t
val fold : ?force:'a force -> ?uniq:uniq -> ?pre:'a node_fn -> ?post:'a node_fn -> ?depth:depth -> ?contents:(key -> contents -> 'a -> 'a Lwt.t) -> ?node:(key -> node -> 'a -> 'a Lwt.t) -> tree -> 'a -> 'a Lwt.t

fold f t acc folds f over t's leafs.

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, in lexicographic order;
  • Call post path n; By default post is the identity.

See force for details about the force parameters. By default it is `And_clear.

See uniq for details about the uniq parameters. By default it is `False.

The fold depth is controlled by the depth parameter.

Stats

type stats = {
  1. nodes : int;
    (*

    Number of node.

    *)
  2. leafs : int;
    (*

    Number of leafs.

    *)
  3. skips : int;
    (*

    Number of lazy nodes.

    *)
  4. depth : int;
    (*

    Maximal depth.

    *)
  5. width : int;
    (*

    Maximal width.

    *)
}

The type for tree stats.

val stats_t : stats Irmin.Type.t
val stats : ?force:bool -> tree -> stats Lwt.t

stats ~force t are t's statistics. If force is true, this will force the reading of lazy nodes. By default it is false.

Concrete Trees

type concrete = [
  1. | `Tree of (step * concrete) list
  2. | `Contents of contents * metadata
]

The type for concrete trees.

val concrete_t : concrete Irmin.Type.t

The value-type for concrete.

val of_concrete : concrete -> tree

of_concrete c is the subtree equivalent of the concrete tree c.

val to_concrete : tree -> concrete Lwt.t

to_concrete t is the concrete tree equivalent of the subtree t.

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.

Performance counters

type counters = {
  1. mutable contents_hash : int;
  2. mutable contents_find : int;
  3. mutable contents_add : int;
  4. mutable node_hash : int;
  5. mutable node_mem : int;
  6. mutable node_add : int;
  7. mutable node_find : int;
  8. mutable node_val_v : int;
  9. mutable node_val_find : int;
  10. mutable node_val_list : int;
}
val counters : unit -> counters
val dump_counters : unit Fmt.t
val reset_counters : unit -> unit
val inspect : tree -> [ `Contents | `Node of [ `Map | `Hash | `Value ] ]

Import/Export

val hash : tree -> hash

hash r c it c's hash in the repository r.

val of_hash : Repo.t -> hash -> tree option Lwt.t

of_hash r h is the the tree object in r having h as hash, or None is no such tree object exists.

val shallow : Repo.t -> hash -> tree

shallow r h is the shallow tree object with the hash h. No check is performed to verify if h actually exists in r.

OCaml

Innovation. Community. Security.