package irmin

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

Module KV.MakeSource

Parameters

Signature

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.

Sourcemodule Schema : Irmin.Schema.S with type Path.step = string with type Path.t = string list with type Branch.t = string with module Contents = C with type Metadata.t = metadata with type Hash.t = hash with type Info.t = info
Sourcetype repo

The type for Irmin repositories.

Sourcetype t

The type for Irmin stores.

The type for key steps.

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

Sourcetype metadata = Schema.Metadata.t

The type for store metadata.

Sourceval metadata_t : metadata Irmin.Type.t
Sourcetype contents = Schema.Contents.t

The type for store contents.

Sourceval contents_t : contents Irmin.Type.t
Sourcetype node

The type for store nodes.

Sourcetype tree

The type for store trees.

The type for object hashes.

Sourcetype commit

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

Sourceval commit_t : repo -> commit Irmin.Type.t

commit_t r is the value type for commit.

Sourcetype 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.

Sourceval branch_t : branch Irmin.Type.t
Sourcetype slice

Type for store slices.

The type for commit info.

Sourcetype lca_error = [
  1. | `Max_depth_reached
  2. | `Too_many_lcas
]

The type for errors associated with functions computing least common ancestors

Sourceval lca_error_t : lca_error Irmin.Type.t
Sourcetype ff_error = [
  1. | `No_change
  2. | `Rejected
  3. | lca_error
]

The type for errors for Head.fast_forward.

Sourceval ff_error_t : ff_error Irmin.Type.t
Sourcemodule Info : sig ... end
Sourcetype contents_key = (hash, C.t) contents_key
Sourceval contents_key_t : contents_key Irmin.Type.t
Sourcetype node_key = hash node_key
Sourceval node_key_t : node_key Irmin.Type.t
Sourcetype commit_key = hash commit_key
Sourceval commit_key_t : commit_key Irmin.Type.t
Sourcemodule Repo : sig ... end

Repositories.

Sourceval empty : repo -> t Lwt.t

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

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval repo : t -> repo

repo t is the repository containing t.

Sourceval tree : t -> tree Lwt.t

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

Sourcemodule Status : sig ... end
Sourceval status : t -> Status.t

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

Sourcemodule Head : sig ... end

Managing the store's heads.

Sourcemodule Hash : Irmin.Hash.S with type t = hash

Object hashes.

Sourcemodule Commit : sig ... end

Commit defines immutable objects to describe store updates.

Sourcemodule Contents : sig ... end

Contents provides base functions for the store's contents.

Sourcemodule Tree : sig ... end

Managing store's trees.

Reads

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sourceval 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
]
Sourceval key : t -> path -> kinded_key option Lwt.t

id t k

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

hash t k

Updates

Sourcetype write_error = [
  1. | Irmin.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.
Sourceval write_error_t : write_error Irmin.Type.t
Sourceval set : ?clear:bool -> ?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.

When clear is set (the default), the tree cache is emptied upon the function's completion, mirroring the effect of invoking Tree.clear.

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

Sourceval set_exn : ?clear:bool -> ?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.

Sourceval set_tree : ?clear:bool -> ?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.

Sourceval set_tree_exn : ?clear:bool -> ?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.

Sourceval remove : ?clear:bool -> ?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).

Sourceval remove_exn : ?clear:bool -> ?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.

Sourceval test_and_set : ?clear:bool -> ?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).

Sourceval test_and_set_exn : ?clear:bool -> ?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.

Sourceval test_and_set_tree : ?clear:bool -> ?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.

Sourceval test_and_set_tree_exn : ?clear:bool -> ?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.

Sourceval test_set_and_get : ?clear:bool -> ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:(unit -> info) -> t -> path -> test:contents option -> set:contents option -> (commit option, write_error) result Lwt.t

test_set_and_get is like test_and_set except it also returns the commit associated with updating the store with the new value if the test_and_set is successful. No commit is returned if there was no update to the store.

Sourceval test_set_and_get_exn : ?clear:bool -> ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:(unit -> info) -> t -> path -> test:contents option -> set:contents option -> commit option Lwt.t

test_set_and_get_exn is like test_set_and_get but raises Failure _ instead.

Sourceval test_set_and_get_tree : ?clear:bool -> ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:(unit -> info) -> t -> path -> test:tree option -> set:tree option -> (commit option, write_error) result Lwt.t

test_set_and_get_tree is like test_set_and_get but for a tree

Sourceval test_set_and_get_tree_exn : ?clear:bool -> ?retries:int -> ?allow_empty:bool -> ?parents:commit list -> info:(unit -> info) -> t -> path -> test:tree option -> set:tree option -> commit option Lwt.t

test_set_and_get_tree_exn is like test_set_and_get_tree but raises Failure _ instead.

Sourceval merge : ?clear:bool -> ?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).

Sourceval merge_exn : ?clear:bool -> ?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.

Sourceval merge_tree : ?clear:bool -> ?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.

Sourceval merge_tree_exn : ?clear:bool -> ?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.

Sourceval with_tree : ?clear:bool -> ?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.

Sourceval with_tree_exn : ?clear:bool -> ?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

Sourceval 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

Sourcetype watch

The type for store watches.

Sourceval watch : t -> ?init:commit -> (commit Irmin.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.

Sourceval watch_key : t -> path -> ?init:commit -> ((commit * tree) Irmin.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.

Sourceval unwatch : watch -> unit Lwt.t

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

Merges and Common Ancestors

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

The type for merge functions.

Sourceval merge_into : into:t -> t merge

merge_into ~into:x ~info: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>.

Sourceval merge_with_branch : t -> branch merge

Same as merge but with a branch ID.

Sourceval merge_with_commit : t -> commit merge

Same as merge but with a commit_id.

Sourceval 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.
Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourcemodule Branch : sig ... end

Manipulate branches.

Sourcemodule Path : Irmin.Path.S with type t = path and type step = step

Path provides base functions for the stores's paths.

Metadata provides base functions for node metadata.

Sourcemodule Backend : Irmin.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 with type Remote.endpoint = endpoint

Backend functions, which might be used by the backends.

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

    Extend the remote type with endpoint.

    *)

Converters to backend types

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

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

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

Save a tree into the database. Does not do any reads.

When clear is set (the default), the tree cache is emptied upon the function's completion, mirroring the effect of invoking Tree.clear.

Deprecated

Sourceval 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