package octez-libs

  1. Overview
  2. Docs
On This Page
  1. Key-value store
A package that contains multiple base libraries used by the Octez suite

Install 

dune-project
 Dependency

www.tezos.com Readme Edit opam file Versions (5)

Authors

  1. T
    Tezos devteam

Maintainers

  1. C
    contact@tezos.com

Sources

tezos-18.1.tar.gz
sha256=aa2f5bc99cc4ca2217c52a1af2a2cdfd3b383208cb859ca2e79ca0903396ca1d
sha512=d68bb3eb615e3dcccc845fddfc9901c95b3c6dc8e105e39522ce97637b1308a7fa7aa1d271351d5933febd7476b2819e1694f31198f1f0919681f1f9cc97cb3a

doc/octez-libs.stdlib-unix/Tezos_stdlib_unix/Key_value_store/index.html

Module Tezos_stdlib_unix.Key_value_storeSource

Sourcetype Tezos_error_monad.Error_monad.error +=
  1. | 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.

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

An abstract representation of a key-value store.

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

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

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

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

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

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

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

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