package irmin
Of_storage
uses a custom storage layer and chosen hash and contents type to create a key-value store.
Parameters
module M : Storage.Make
module V : Contents.S
Signature
type hash = H.t
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.
type step = Schema.Path.step
The type for key
steps.
type path = Schema.Path.t
The type for store keys. A key is a sequence of step
s.
type metadata = Schema.Metadata.t
The type for store metadata.
type contents = Schema.Contents.t
The type for store contents.
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.
type info = Schema.Info.t
The type for commit info.
The type for errors associated with functions computing least common ancestors
The type for errors for Head.fast_forward
.
module Info : sig ... end
type contents_key = hash
val contents_key_t : contents_key Type.t
type node_key = hash
type commit_key = hash
val commit_key_t : commit_key Type.t
module Repo : sig ... end
Repositories.
empty repo
is a temporary, empty store. Becomes a normal temporary store after the first update.
main r
is a persistent store based on r
's main branch. This operation is cheap, can be repeated multiple times.
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
.
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.
tree t
is t
's current tree. Contents is not allowed at the root of the tree.
module Status : sig ... end
module Head : sig ... end
Managing the store's heads.
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
kind
is Tree.kind
applied to t
's root tree.
mem_tree t
is Tree.mem_tree
applied to t
's root tree.
find_all t
is Tree.find_all
applied to t
's root tree.
get_all t
is Tree.get_all
applied on t
's root tree.
find_tree t
is Tree.find_tree
applied to t
's root tree.
get_tree t k
is Tree.get_tree
applied to t
's root tree.
val key : t -> path -> kinded_key option Lwt.t
id t k
Updates
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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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 test_set_and_get :
?retries:int ->
?allow_empty:bool ->
?parents:commit list ->
info:(unit -> info) ->
t ->
path ->
test:contents option ->
set:contents option ->
(commit option, write_error) Stdlib.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.
val test_set_and_get_exn :
?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.
val test_set_and_get_tree :
?retries:int ->
?allow_empty:bool ->
?parents:commit list ->
info:(unit -> info) ->
t ->
path ->
test:tree option ->
set:tree option ->
(commit option, write_error) Stdlib.result Lwt.t
test_set_and_get_tree
is like test_set_and_get
but for a tree
val test_set_and_get_tree_exn :
?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.
val merge :
?retries:int ->
?allow_empty:bool ->
?parents:commit list ->
info:Info.f ->
old:contents option ->
t ->
path ->
contents option ->
(unit, write_error) Stdlib.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) Stdlib.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) Stdlib.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
, useset
and discard any concurrent updates tok
. - if
strategy = `Test_and_set
(default), usetest_and_set
and ensure that no concurrent operations are updatingk
. - if
strategy = `Merge
, usemerge
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
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
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.
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.
Merges and Common Ancestors
type 'a merge =
info:Info.f ->
?max_depth:int ->
?n:int ->
'a ->
(unit, Merge.conflict) Stdlib.result Lwt.t
The type for merge functions.
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>
.
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 ismax_int
). ReturnError `Max_depth_reached
if this depth is exceeded.n
is the maximum expected number of lcas. Stop the exploration as soon asn
lcas are found. ReturnError `Too_many_lcas
if morelcas
are found.
val lcas_with_branch :
t ->
?max_depth:int ->
?n:int ->
branch ->
(commit list, lca_error) Stdlib.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) Stdlib.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.
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.
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.
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.
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_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
.
val save_contents :
[> Perms.write ] Backend.Contents.t ->
contents ->
contents_key Lwt.t
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