package irmin

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

Irmin stores

Irmin stores are tree-like read-write stores with extended capabilities. They allow an application (or a collection of applications) to work with multiple local states, which can be forked and merged programmatically, without having to rely on a global state. In a way very similar to version control systems, Irmin local states are called branches.

There are two kinds of store in Irmin: the ones based on persistent named branches and the ones based temporary detached heads. These exist relative to a local, larger (and shared) store, and have some (shared) contents. This is exactly the same as usual version control systems, that the informed user can see as an implicit purely functional data-structure.

module Schema : Schema.S with type Hash.t = hash with type Contents.t = Contents.json
type repo

The type for Irmin repositories.

type t

The type for Irmin stores.

type step = Schema.Path.step

The type for key steps.

val step_t : step Type.t
type path = Schema.Path.t

The type for store keys. A key is a sequence of steps.

val path_t : path Type.t
type metadata = Schema.Metadata.t

The type for store metadata.

val metadata_t : metadata Type.t
type contents = Schema.Contents.t

The type for store contents.

val contents_t : contents Type.t
type node

The type for store nodes.

val node_t : node Type.t
type tree

The type for store trees.

val tree_t : tree Type.t
val hash_t : hash Type.t
type commit

Type for `Commit identifiers. Similar to Git's commit SHA1s.

val commit_t : repo -> commit Type.t

commit_t r is the value type for commit.

type branch = Schema.Branch.t

Type for persistent branch names. Branches usually share a common global namespace and it's the user's responsibility to avoid name clashes.

val branch_t : branch Type.t
type slice

Type for store slices.

val slice_t : slice Type.t
type info = Schema.Info.t

The type for commit info.

val info_t : info Type.t
type lca_error = [
  1. | `Max_depth_reached
  2. | `Too_many_lcas
]

The type for errors associated with functions computing least common ancestors

val lca_error_t : lca_error Type.t
type ff_error = [
  1. | `No_change
  2. | `Rejected
  3. | lca_error
]

The type for errors for Head.fast_forward.

val ff_error_t : ff_error Type.t
module Info : sig ... end
type contents_key = hash
val contents_key_t : contents_key Type.t
type node_key = hash
val node_key_t : node_key Type.t
type commit_key = hash
val commit_key_t : commit_key Type.t
module Repo : sig ... end

Repositories.

val empty : repo -> t Lwt.t

empty repo is a temporary, empty store. Becomes a normal temporary store after the first update.

val main : repo -> t Lwt.t

main r is a persistent store based on r's main branch. This operation is cheap, can be repeated multiple times.

val of_branch : repo -> branch -> t Lwt.t

of_branch r name is a persistent store based on the branch name. Similar to main, but use name instead of Irmin.Branch.S.main.

val of_commit : commit -> t Lwt.t

of_commit c is a temporary store, based on the commit c.

Temporary stores do not have stable names: instead they can be addressed using the hash of the current commit. Temporary stores are similar to Git's detached heads. In a temporary store, all the operations are performed relative to the current head and update operations can modify the current head: the current stores's head will automatically become the new head obtained after performing the update.

val repo : t -> repo

repo t is the repository containing t.

val tree : t -> tree Lwt.t

tree t is t's current tree. Contents is not allowed at the root of the tree.

module Status : sig ... end
val status : t -> Status.t

status t is t's status. It can either be a branch, a commit or empty.

module Head : sig ... end

Managing the store's heads.

module Hash : Hash.S with type t = hash

Object hashes.

module Commit : sig ... end

Commit defines immutable objects to describe store updates.

module Contents : sig ... end

Contents provides base functions for the store's contents.

module Tree : sig ... end

Managing store's trees.

Reads

val kind : t -> path -> [ `Contents | `Node ] option Lwt.t

kind is Tree.kind applied to t's root tree.

val list : t -> path -> (step * tree) list Lwt.t

list t is Tree.list applied to t's root tree.

val mem : t -> path -> bool Lwt.t

mem t is Tree.mem applied to t's root tree.

val mem_tree : t -> path -> bool Lwt.t

mem_tree t is Tree.mem_tree applied to t's root tree.

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

find_all t is Tree.find_all applied to t's root tree.

val find : t -> path -> contents option Lwt.t

find t is Tree.find applied to t's root tree.

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

get_all t is Tree.get_all applied on t's root tree.

val get : t -> path -> contents Lwt.t

get t is Tree.get applied to t's root tree.

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

find_tree t is Tree.find_tree applied to t's root tree.

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

get_tree t k is Tree.get_tree applied to t's root tree.

type kinded_key := [
  1. | `Contents of contents_key
  2. | `Node of node_key
]
val key : t -> path -> kinded_key option Lwt.t

id t k

val hash : t -> path -> hash option Lwt.t

hash t k

Updates

type write_error = [
  1. | Merge.conflict
  2. | `Too_many_retries of int
  3. | `Test_was of tree option
]

The type for write errors.

  • Merge conflict.
  • Concurrent transactions are competing to get the current operation committed and too many attemps have been tried (livelock).
  • A "test and set" operation has failed and the current value is v instead of the one we were waiting for.
val write_error_t : write_error Type.t
val set : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> contents -> (unit, write_error) result Lwt.t

set t k ~info v sets k to the value v in t. Discard any previous results but ensure that no operation is lost in the history.

This function always uses Metadata.default as metadata. Use set_tree with `Contents (c, m) for different ones.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

val set_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> contents -> unit Lwt.t

set_exn is like set but raise Failure _ instead of using a result type.

val set_tree : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> tree -> (unit, write_error) result Lwt.t

set_tree is like set but for trees.

val set_tree_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> tree -> unit Lwt.t

set_tree is like set_exn but for trees.

val remove : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> (unit, write_error) result Lwt.t

remove t ~info k remove any bindings to k in t.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

val remove_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> unit Lwt.t

remove_exn is like remove but raise Failure _ instead of a using result type.

val test_and_set : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> test:contents option -> set:contents option -> (unit, write_error) result Lwt.t

test_and_set ~test ~set is like set but it atomically checks that the tree is test before modifying it to set.

This function always uses Metadata.default as metadata. Use test_and_set_tree with `Contents (c, m) for different ones.

The result is Error (`Test t) if the current tree is t instead of test.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

val test_and_set_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> test:contents option -> set:contents option -> unit Lwt.t

test_and_set_exn is like test_and_set but raise Failure _ instead of using a result type.

val test_and_set_tree : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> test:tree option -> set:tree option -> (unit, write_error) result Lwt.t

test_and_set_tree is like test_and_set but for trees.

val test_and_set_tree_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> t -> path -> test:tree option -> set:tree option -> unit Lwt.t

test_and_set_tree_exn is like test_and_set_exn but for trees.

val merge : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> old:contents option -> t -> path -> contents option -> (unit, write_error) result Lwt.t

merge ~old is like set but merge the current tree and the new tree using old as ancestor in case of conflicts.

This function always uses Metadata.default as metadata. Use merge_tree with `Contents (c, m) for different ones.

The result is Error (`Conflict c) if the merge failed with the conflict c.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

val merge_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> old:contents option -> t -> path -> contents option -> unit Lwt.t

merge_exn is like merge but raise Failure _ instead of using a result type.

val merge_tree : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> old:tree option -> t -> path -> tree option -> (unit, write_error) result Lwt.t

merge_tree is like merge_tree but for trees.

val merge_tree_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:Info.f -> old:tree option -> t -> path -> tree option -> unit Lwt.t

merge_tree is like merge_tree but for trees.

val with_tree : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> ?strategy:[ `Set | `Test_and_set | `Merge ] -> info:Info.f -> t -> path -> (tree option -> tree option Lwt.t) -> (unit, write_error) result Lwt.t

with_tree t k ~info f replaces atomically the subtree v under k in the store t by the contents of the tree f v, using the commit info info ().

If v = f v and allow_empty is unset (default) then, the operation is a no-op.

If v != f v and no other changes happen concurrently, f v becomes the new subtree under k. If other changes happen concurrently to that operations, the semantics depend on the value of strategy:

  • if strategy = `Set, use set and discard any concurrent updates to k.
  • if strategy = `Test_and_set (default), use test_and_set and ensure that no concurrent operations are updating k.
  • if strategy = `Merge, use merge and ensure that concurrent updates and merged with the values present at the beginning of the transaction.

Note: Irmin transactions provides snapshot isolation guarantees: reads and writes are isolated in every transaction, but only write conflicts are visible on commit.

val with_tree_exn : ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> ?strategy:[ `Set | `Test_and_set | `Merge ] -> info:Info.f -> t -> path -> (tree option -> tree option Lwt.t) -> unit Lwt.t

with_tree_exn is like with_tree but raise Failure _ instead of using a return type.

Clones

val clone : src:t -> dst:branch -> t Lwt.t

clone ~src ~dst makes dst points to Head.get src. dst is created if needed. Remove the current contents en dst if src is empty.

Watches

type watch

The type for store watches.

val watch : t -> ?init:commit -> (commit Diff.t -> unit Lwt.t) -> watch Lwt.t

watch t f calls f every time the contents of t's head is updated.

Note: even if f might skip some head updates, it will never be called concurrently: all consecutive calls to f are done in sequence, so we ensure that the previous one ended before calling the next one.

val watch_key : t -> path -> ?init:commit -> ((commit * tree) Diff.t -> unit Lwt.t) -> watch Lwt.t

watch_key t key f calls f every time the key's value is added, removed or updated. If the current branch is deleted, no signal is sent to the watcher.

val unwatch : watch -> unit Lwt.t

unwatch w disable w. Return once the w is fully disabled.

Merges and Common Ancestors

type 'a merge = info:Info.f -> ?max_depth:int -> ?n:int -> 'a -> (unit, Merge.conflict) result Lwt.t

The type for merge functions.

val merge_into : into:t -> t merge

merge_into ~into i t merges t's current branch into x's current branch using the info i. After that operation, the two stores are still independent. Similar to git merge <branch>.

val merge_with_branch : t -> branch merge

Same as merge but with a branch ID.

val merge_with_commit : t -> commit merge

Same as merge but with a commit_id.

val lcas : ?max_depth:int -> ?n:int -> t -> t -> (commit list, lca_error) result Lwt.t

lca ?max_depth ?n msg t1 t2 returns the collection of least common ancestors between the heads of t1 and t2 branches.

  • max_depth is the maximum depth of the exploration (default is max_int). Return Error `Max_depth_reached if this depth is exceeded.
  • n is the maximum expected number of lcas. Stop the exploration as soon as n lcas are found. Return Error `Too_many_lcas if more lcas are found.
val lcas_with_branch : t -> ?max_depth:int -> ?n:int -> branch -> (commit list, lca_error) result Lwt.t

Same as lcas but takes a branch ID as argument.

val lcas_with_commit : t -> ?max_depth:int -> ?n:int -> commit -> (commit list, lca_error) result Lwt.t

Same as lcas but takes a commmit as argument.

History

module History : Graph.Sig.P with type V.t = commit

An history is a DAG of heads.

val history : ?depth:int -> ?min:commit list -> ?max:commit list -> t -> History.t Lwt.t

history ?depth ?min ?max t is a view of the history of the store t, of depth at most depth, starting from the t's head (or from max if the head is not set) and stopping at min if specified.

val last_modified : ?depth:int -> ?n:int -> t -> path -> commit list Lwt.t

last_modified ?number c k is the list of the last number commits that modified path, in ascending order of date. depth is the maximum depth to be explored in the commit graph, if any. Default value for number is 1.

module Branch : sig ... end

Manipulate branches.

module Path : Path.S with type t = path and type step = step

Path provides base functions for the stores's paths.

module Metadata : Metadata.S with type t = metadata

Metadata provides base functions for node metadata.

module Backend : Backend.S with module Schema = Schema with type Slice.t = slice and type Repo.t = repo and module Hash = Hash and module Node.Path = Path and type Contents.key = contents_key and type Node.key = node_key and type Commit.key = commit_key

Backend functions, which might be used by the backends.

type Irmin__.Remote.t +=
  1. | E of Backend.Remote.endpoint
    (*

    Extend the remote type with endpoint.

    *)

Converters to backend types

val of_backend_node : repo -> Backend.Node.value -> node
val to_backend_node : node -> Backend.Node.value Lwt.t
val to_backend_portable_node : node -> Backend.Node_portable.t Lwt.t
val to_backend_commit : commit -> Backend.Commit.value

to_backend_commit c is the backend commit object associated with the commit c.

val of_backend_commit : repo -> Backend.Commit.Key.t -> Backend.Commit.value -> commit

of_backend_commit r k c is the commit associated with the backend commit object c that hash key k in r.

Save a content into the database

val save_tree : ?clear:bool -> repo -> [> Perms.write ] Backend.Contents.t -> [> Perms.read_write ] Backend.Node.t -> tree -> kinded_key Lwt.t

Save a tree into the database. Does not do any reads. If clear is set (it is by default), the tree cache will be cleared after the save.

Deprecated

val master : repo -> t Lwt.t
  • deprecated

    Use main instead

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