Module type Irmin.S

module type S = sig .. end
Irmin stores.


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 t 
The type for branch-consistent stores.
type step 
The type for Irmin.S.key steps.
type key 
The type for store keys. A key is a sequence of Irmin.S.steps.
type metadata 
The type for store metadata.
type contents 
The type for store contents.
type node 
The type for store nodes.
type tree = [ `Contents of contents * metadata
| `Empty
| `Node of node ]
The type for store trees.
type commit 
Type for commit identifiers. Similar to Git's commit SHA1s.
type branch 
Type for persistent branch names. Branches usually share a common global namespace and it's the user's responsibility to avoid name clashes.
type slice 
Type for store slices.
type lca_error = [ `Max_depth_reached | `Too_many_lcas ] 
The type for errors associated with functions computing least common ancestors
type ff_error = [ `Max_depth_reached | `No_change | `Rejected | `Too_many_lcas ] 
The type for errors for fast_forward.
module Repo: sig .. end
Repositories.
val empty : Repo.t -> t Lwt.t
empty repo is a temporary, empty store. Becomes a normal temporary store after the first update.
val master : Repo.t -> t Lwt.t
master repo is a persistent store based on r's master branch. This operation is cheap, can be repeated multiple times.
val of_branch : Repo.t -> branch -> t Lwt.t
of_branch r name is a persistent store based on the branch name. Similar to master, but use name instead Irmin.Branch.S.master.
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.t
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
Status provides base functions for store statuses.
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 Commit: sig .. end
Commit defines immutable objects to describe store updates.

Managing store's trees.
module Tree: sig .. end
module Contents: sig .. end
Contents provides base functions for the store's contents.

Reads


val kind : t -> key -> [ `Contents | `Empty | `Node ] Lwt.t
kind is Irmin.S.Tree.kind applied to t's root tree.
val list : t -> key -> (step * [ `Contents | `Node ]) list Lwt.t
list t is Irmin.S.Tree.list applied to t's root tree.
val mem : t -> key -> bool Lwt.t
mem t is Irmin.S.Tree.mem applied to t's root tree.
val mem_tree : t -> key -> bool Lwt.t
mem_tree t is Irmin.S.Tree.mem_tree applied to t's root tree.
val find_all : t ->
key -> (contents * metadata) option Lwt.t
find_all t is Irmin.S.Tree.find_all applied to t's root tree.
val find : t -> key -> contents option Lwt.t
find t is Irmin.S.Tree.find applied to t's root tree.
val get_all : t -> key -> (contents * metadata) Lwt.t
get_all t is Irmin.S.Tree.get_all applied on t's root tree.
val get : t -> key -> contents Lwt.t
get t is Irmin.S.Tree.get applied to t's root tree.
val find_tree : t -> key -> tree Lwt.t
find_tree t is Irmin.S.Tree.find_tree applied to t's root tree.

Transactions


type 'a transaction = ?allow_empty:bool ->
?strategy:[ `Merge | `Set | `Test_and_set ] ->
?max_depth:int -> ?n:int -> info:Irmin.Info.f -> 'a -> unit Lwt.t
The type for transactions.
val with_tree : t ->
key -> (tree -> tree Lwt.t) transaction
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:

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

val set : t ->
key ->
?metadata:metadata -> contents transaction
set t k ~info v is with_tree t k ~info (fun tree -> Tree.add
      tree [] v)
.
val set_tree : t -> key -> tree transaction
set_tree t k ~info v is with_tree t k ~info (fun tree ->
      Tree.add_tree tree [] v)
.
val remove : t -> key transaction
remove t i k is with_tree t i k (fun tree -> Tree.remove tree
      [])
.

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 Irmin.S.empty.

Watches


type watch 
The type for store watches.
val watch : t ->
?init:commit ->
(commit Irmin.diff -> 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 ->
key ->
?init:commit ->
((commit * tree) Irmin.diff -> 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:Irmin.Info.f ->
?max_depth:int ->
?n:int -> 'a -> (unit, Irmin.Merge.conflict) Result.result Lwt.t
The type for merge functions.
val merge : into:t -> t merge
merge ~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 Irmin.S.merge but with a branch ID.
val merge_with_commit : t -> commit merge
Same as Irmin.S.merge but with a commit ID.
val lcas : ?max_depth:int ->
?n:int ->
t ->
t -> (commit list, lca_error) Result.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.


val lcas_with_branch : t ->
?max_depth:int ->
?n:int ->
branch ->
(commit list, lca_error) Result.result Lwt.t
Same as Irmin.S.lcas but takes a branch ID as argument.
val lcas_with_commit : t ->
?max_depth:int ->
?n:int ->
commit ->
(commit list, lca_error) Result.result Lwt.t
Same as Irmin.S.lcas but takes a commit ID 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 max (or from the t's head if the list of heads is empty) and stopping at min if specified.
module Branch: sig .. end
Manipulate branches.
module Key: Irmin.Path.S  with type t = key and type step = step
Key provides base functions for the stores's paths.
module Metadata: Irmin.Metadata.S  with type t = metadata
Metadata provides base functions for node metadata.

Value Types


val step_t : step Irmin.Type.t
step_t is the value type for Irmin.S.step.
val key_t : key Irmin.Type.t
key_t is the value type for Irmin.S.key.
val metadata_t : metadata Irmin.Type.t
metadata_t is the value type for Irmin.S.metadata.
val contents_t : contents Irmin.Type.t
contents_t is the value type for Irmin.S.contents.
val node_t : node Irmin.Type.t
node_t is the value type for Irmin.S.node.
val tree_t : tree Irmin.Type.t
tree_t is the value type for Irmin.S.tree.
val commit_t : Repo.t -> commit Irmin.Type.t
commit_t r is the value type for Irmin.S.commit.
val branch_t : branch Irmin.Type.t
branch_t is the value type for Irmin.S.branch.
val slice_t : slice Irmin.Type.t
slice_t is the value type for Irmin.S.slice.
val kind_t : [ `Contents | `Node ] Irmin.Type.t
kind_t is the value type for values returned by Irmin.S.kind.
val kinde_t : [ `Contents | `Empty | `Node ] Irmin.Type.t
kind_t is like Irmin.S.kind_t but also allow `Empty values.
val lca_error_t : lca_error Irmin.Type.t
lca_error_t is the value type for Irmin.S.lca_error.
val ff_error_t : ff_error Irmin.Type.t
ff_error_t is the value type for Irmin.S.ff_error.
module Private: sig .. end
Private functions, which might be used by the backends.