package irmin-mirage-git

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

Parameters

module C : Mirage_clock.PCLOCK

Signature

include Mirage_kv.RW

Read-write Stores

The functions set and remove will cause a flush in the underlying storage layer every time, which can degrade performance.

include Mirage_kv.RO

Read-only key-value stores

type nonrec error = private [>
  1. | Mirage_kv.error
]

The type for errors.

val pp_error : error Fmt.t

pp_error is the pretty-printer for errors.

type t

The type representing the internal state of the key-value store.

val disconnect : t -> unit Lwt.t

Disconnect from the key-value store. While this might take some time to complete, it can never result in an error.

type key = Mirage_kv.Key.t

The type for keys.

val exists : t -> key -> ([ `Value | `Dictionary ] option, error) Stdlib.result Lwt.t

exists t k is Some `Value if k is bound to a value in t, Some `Dictionary if k is a prefix of a valid key in t and None if no key with that prefix exists in t.

exists answers two questions: does the key exist and is it referring to a value or a dictionary.

An error occurs when the underlying storage layer fails.

val get : t -> key -> (string, error) Stdlib.result Lwt.t

get t k is the value bound to k in t.

The result is Error (`Value_expected k) if k refers to a dictionary in t.

val get_partial : t -> key -> offset:Optint.Int63.t -> length:int -> (string, error) Stdlib.result Lwt.t

get_partial t k ~offset ~length is the length bytes wide value bound at offset of k in t.

If the size of k is less than offset, get_partial returns an empty string. If the size of k is less than offset+length, get_partial returns a short string. The result is Error (`Value_expected k) if k refers to a dictionary in t.

val list : t -> key -> ((key * [ `Value | `Dictionary ]) list, error) Stdlib.result Lwt.t

list t k is the list of entries and their types in the dictionary referenced by k in t. The returned keys are all absolute (i.e. Key.add k entry).

The result is Error (`Dictionary_expected k) if k refers to a value in t.

val last_modified : t -> key -> (Ptime.t, error) Stdlib.result Lwt.t

last_modified t k is the last time the value bound to k in t has been modified.

When the value bound to k is a dictionary, the implementation is free to decide how to compute a last modified timestamp, or return Error (`Value_expected _).

val digest : t -> key -> (string, error) Stdlib.result Lwt.t

digest t k is the unique digest of the value bound to k in t.

When the value bound to k is a dictionary, the implementation is allowed to return Error (`Value_expected _). Otherwise, the digest is a unique and deterministic digest of its entries.

val size : t -> key -> (Optint.Int63.t, error) Stdlib.result Lwt.t

size t k is the size of k in t.

type nonrec write_error = private [>
  1. | Mirage_kv.write_error
]

The type for write errors.

val pp_write_error : write_error Fmt.t

The pretty-printer for pp_write_error.

val allocate : t -> key -> ?last_modified:Ptime.t -> Optint.Int63.t -> (unit, write_error) Stdlib.result Lwt.t

allocate t key ~last_modified size allocates space for key in t with the provided size and last_modified. This is useful for e.g. append-only backends that could still use set_partial. The data will be filled with 0. If key already exists, Error (`Already_present key) is returned. If there's not enough space, Error `No_space is returned.

val set : t -> key -> string -> (unit, write_error) Stdlib.result Lwt.t

set t k v replaces the binding k -> v in t.

Durability is guaranteed.

val set_partial : t -> key -> offset:Optint.Int63.t -> string -> (unit, write_error) Stdlib.result Lwt.t

set_partial t k offset v attempts to write v at offset in the value bound to k in t. If k contains directories that do not exist, set_partial will attempt to create them. If the size of k is less than offset, set_partial appends v at the end of k. If the size of k is greater than offset+length of v, set_partial leaves the last bytes of k unchanged.

The result is Error (`Value_expected k) if k refers to a dictionary in t.

val remove : t -> key -> (unit, write_error) Stdlib.result Lwt.t

remove t k removes any binding of k in t. If k was bound to a dictionary, the full dictionary will be removed.

Durability is guaranteed.

val rename : t -> source:key -> dest:key -> (unit, write_error) Stdlib.result Lwt.t

rename t source dest rename source to dest in t. If source and dest are both bound to values in t, dest is removed and the binding of source is moved to dest. If dest is bound to a dictionary in t, source is moved inside dest. If source is bound to a dictionary, the full dictionary is moved.

The result is Error (`Not_found source) if source does not exists in t. The result is Error (`Value_expected source) if source is bound to a dictionary in t and dest is bound to a value in t. The result id Error (`Rename_source_prefix (source, dest)) if source is a prefix of dest, and source is a directory.

val batch : t -> ?retries:int -> (t -> 'a Lwt.t) -> 'a Lwt.t

batch t f run f in batch. Ensure the durability of operations.

Since a batch is applied at once, the readings inside a batch will return the state before the entire batch. Concurrent operations will not affect other ones executed during the batch.

Batch applications can fail to apply if other operations are happening concurrently. In case of failure, f will run again with the most recent version of t. The result is Error `Too_many_retries if f is run for more then retries attemps (default is 42).

val connect : ?depth:int -> ?branch:string -> ?root:key -> ?ctx:Mimic.ctx -> ?headers:(string * string) list -> ?author:(unit -> string) -> ?msg:([ `Set of key | `Remove of key | `Batch ] -> string) -> G.t -> string -> t Lwt.t

connect ?depth ?branch ?path ?author ?msg g c uri clones the given uri into g repository, using the given branch, depth and '/'-separated sub-path. By default, branch is main, depth is 1 and path is empty, ie. reads will be relative to the root of the repository. author, msg and c are used to create new commit info values on every update. By defaut author is fun () -> "irmin" <irmin@mirage.io> and msg returns basic information about the kind of operations performed.

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