Module Generic_key.Make

Parameters

module Hash : Hash.S
module Contents_key : Key.S with type hash = Hash.t
module Node_key : Key.S with type hash = Hash.t

Signature

include Node_intf.S_generic_key with type hash = Hash.t and type contents_key = Contents_key.t and type node_key = Node_key.t

Node values

type t

The type for node values.

val t : t Type.t
val encoding : t Data_encoding.t

encoding is the data_encoding for t.

type contents_key = Contents_key.t

The type for contents keys.

val contents_key_t : contents_key Type.t
val contents_key_encoding : contents_key Data_encoding.t

contents_key_encoding is the data_encoding for contents_key.

type node_key = Node_key.t

The type for node keys.

val node_key_t : node_key Type.t
val node_key_encoding : node_key Data_encoding.t

node_key_encoding is the data_encoding for node_key.

type value = [
  1. | `Node of node_key
  2. | `Contents of contents_key
]

The type for either (node) keys or (contents) keys

val value_t : value Type.t
val value_encoding : value Data_encoding.t

value_encoding is the data_encoding for value.

type hash = Hash.t

The type of hashes of values.

val hash_t : hash Type.t
val hash_encoding : hash Data_encoding.t

hash_encoding is the data_encoding for hash.

val of_list : (Path.step * value) list -> t

of_list l is the node n such that list n = l.

val list : ?offset:int -> ?length:int -> ?cache:bool -> t -> (Path.step * value) list

list t is the contents of t. offset and length are used to paginate results.

val of_seq : (Path.step * value) Import.Seq.t -> t

of_seq s is the node n such that seq n = s.

val seq : ?offset:int -> ?length:int -> ?cache:bool -> t -> (Path.step * value) Import.Seq.t

seq t is the contents of t. offset and length are used to paginate results.

See caching for an explanation of the cache parameter

val empty : unit -> t

empty () is the empty node.

val is_empty : t -> bool

is_empty t is true iff t is empty.

val length : t -> int

length t is the number of entries in t.

val hash_exn : ?force:bool -> t -> hash

hash_exn t is the hash of t.

Another way of computing it is Hash.Typed(Hash)(Node).hash t which computes the pre-hash of t before hashing it using Hash. hash_exn might be faster because the it may be optimised (e.g. it may use caching).

hash_exn t is hash_exn ~force:true t which is not expected to raise an exception. hash_exn ~force:false t will raise Not_found if the hash requires IOs to be computed.

val clear : t -> unit

Cleanup internal caches.

val find : ?cache:bool -> t -> Path.step -> value option

find t s is the value associated with s in t.

A node can point to user-defined contents. The edge between the node and the contents is labeled by a Path.step.

See caching for an explanation of the cache parameter

val add : t -> Path.step -> value -> t

add t s v is the node where find t v is Some s but is similar to t otherwise.

val remove : t -> Path.step -> t

remove t s is the node where find t s is None but is similar to t otherwise.

caching

cache regulates the caching behaviour regarding the node's internal data which may be lazily loaded from the backend, depending on the node implementation.

cache defaults to true which may greatly reduce the IOs and the runtime but may also increase the memory consumption.

cache = false doesn't replace a call to clear, it only prevents the storing of new data, it doesn't discard the existing one.

Recursive Nodes

Some Node implementations (like brassaia-pack's inodes) can represent a node as a set of nodes. One operation on such "high-level" node corresponds to a sequence of recursive calls to the underlying "lower-level" nodes. Note: theses effects are not in the Lwt monad on purpose (so Tree.hash and Tree.equal are not in the Lwt monad as well).

type effect := expected_depth:int -> node_key -> t option

The type for read effects.

val with_handler : (effect -> effect) -> t -> t

with_handler f replace the current effect handler h by f h. f h will be called for all the recursive read effects that are required by recursive operations on nodes. .

type head := [
  1. | `Node of (Path.step * value) list
  2. | `Inode of int * (int * hash) list
]
val head : t -> head

Reveal the shallow internal structure of the node.

Only hashes and not keys are revealed in the `Inode case, this is because these inodes might not be keyed yet.

merging

val merge : contents:contents_key option Merge.t -> node:node_key option Merge.t -> t Merge.t

merge is the merge function for nodes.

exception Dangling_hash of {
  1. context : string;
  2. hash : hash;
}
module Portable : Node_intf.Portable with type node := t and type hash := hash