package irmin

  1. Overview
  2. Docs
package irmin
Legend:
Library
Module
Module type
Parameter
Class
Class type

Make provides a simple node implementation, parameterized by the contents and notes keys K, paths P and metadata M.

Parameters

module H : Hash.S
module P : sig ... end
module M : sig ... end

Signature

Node values

type t

The type for node values.

val t : t Type.t
type metadata = M.t

The type for node metadata.

val metadata_t : metadata Type.t
type hash = H.t

The type for keys.

val hash_t : hash Type.t
type step = P.step

The type for steps between nodes.

val step_t : step Type.t
type value = [
  1. | `Node of hash
  2. | `Contents of hash * metadata
]

The type for either (node) keys or (contents) keys combined with their metadata.

val value_t : value Type.t
val of_list : (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 -> (step * value) list

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

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.

val of_seq : (unit -> (step * value) Seq.node) -> t

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

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

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 : 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 -> 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 step.

See caching for an explanation of the cache parameter

val add : t -> 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 -> step -> t

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

val default : metadata

default is the default metadata value.

Proofs

type proof = [
  1. | `Blinded of hash
  2. | `Values of (step * value) list
  3. | `Inode of int * (int * proof) list
]

The type for proof trees.

val proof_t : proof Type.t
val to_proof : t -> proof
val of_proof : depth:int -> proof -> t option
exception Dangling_hash of {
  1. context : string;
  2. hash : hash;
}
type head := [
  1. | `Node of (step * value) list
  2. | `Inode of int * (int * hash) list
]
val head : t -> head

Recursive Nodes

Some Node implementations (like irmin-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 -> hash -> 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. .

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct