octez-libs 19.0 · OCaml Package

type Tezos_error_monad.Error_monad.error +=

| Missing_stored_kvs_data of string * int

This error is returned when the requested data is not found.

Key-value store

This module defines a simple key-value store. The design is minimal and aims to be:

easy to use

safe when used in a concurrent setting

This key-value store also features a best effort mechanism relying on a cache to avoid I/Os.

This key-value store assumes keys have a flat structure with a first layer of virtual directories and fixed-size virtual files in each directory. Each virtual directory is backed by a single physical file. Values are stored in virtual files, which are mapped sequentially in their virtual directory.

type ('dir, 'file, 'value) t

An abstract representation of a key-value store.

type ('file, 'value) directory_spec

A directory_spec specifies the layout of virtual files storing data of type 'value, as well as the name of the underlying physical file.

val directory : 
  ?encoded_value_size:int ->
  'value Data_encoding.t ->
  string ->
  ('value -> 'value -> bool) ->
  ('file -> int) ->
  ('file, 'value) directory_spec

directory ?encoded_value_size value_encoding path eq index_of describes a virtual directory.

encoded_value_size is the size in bytes of values encoded with value_encoding. If value_encoding does not respect this property, the behaviour of the store is undefined. If encoded_value_size is not given, value_encoding must be of fixed length.
value_encoding is an encoding for the content of virtual files.
path is the path of the physical file in which the directory is to be stored.
eq is an equality function on the contents of virtual files.
index_of gives the index of a given file in the directory.

raises Invalid_argument
if encoded_value_size=None and value_encoding does not have a fixed length.

val init : 
  lru_size:int ->
  ('dir -> ('file, 'value) directory_spec) ->
  ('dir, 'file, 'value) t

init ~lru_size directory_of initialises a key-value store. This is a design where each directory is stored into a single file.

For each virtual directory, we use directory_of to get its specification, including its physical location and how data is layed out in its backing file.

lru_size is a parameter that represents the number of different values that can be in memory. It is up to the user of this library to decide this number depending on the sizes of the values.

val close : ('dir, 'file, 'value) t -> unit Lwt.t

close kvs waits until all pending reads and writes are completed and closes the key-value store.

val write_value : 
  ?override:bool ->
  ('dir, 'file, 'value) t ->
  'dir ->
  'file ->
  'value ->
  unit Tezos_error_monad.Error_monad.tzresult Lwt.t

write_value ?(override=false) t key value writes a value in the key value store. If a previous writing or read failed, the function will try again to write the value. If override is true, the value will be written even though there is already a written value for this key.

val write_values : 
  ?override:bool ->
  ('dir, 'file, 'value) t ->
  ('dir * 'file * 'value) Tezos_error_monad.TzLwtreslib.Seq.t ->
  unit Tezos_error_monad.Error_monad.tzresult Lwt.t

write_values ?(override=false) t seq writes a sequence of keys values onto the store (see write_value). If an error occurs, the first error is returned. This function guarantees that up to the data for which the error occured, the values where stored onto the disk.

val read_value : 
  ('dir, 'file, 'value) t ->
  'dir ->
  'file ->
  'value Tezos_error_monad.Error_monad.tzresult Lwt.t

read_value t key reads the value associated to key in the store. Fails if no value where attached to this key. The value read is the last one that was produced by a successful write.

val read_values : 
  ('dir, 'file, 'value) t ->
  ('dir * 'file) Tezos_error_monad.TzLwtreslib.Seq.t ->
  ('dir * 'file * 'value Tezos_error_monad.Error_monad.tzresult)
    Tezos_error_monad.TzLwtreslib.Seq_s.t

read_values t keys produces a sequence of values associaed to the sequence of keys. This function is almost instantaneous since no reads are performed. Reads are done when the caller consumes the values of the sequence returned.

val value_exists : ('dir, 'file, 'value) t -> 'dir -> 'file -> bool Lwt.t

Same as read_value expect that this function returns whether the given entry exists without reading it.

val values_exist : 
  ('dir, 'file, 'value) t ->
  ('dir * 'file) Tezos_error_monad.TzLwtreslib.Seq.t ->
  ('dir * 'file * bool) Tezos_error_monad.TzLwtreslib.Seq_s.t

Same as read_values expect that this function returns whether the given entries exist without reading them.

package octez-libs

Key-value store