package octez-libs

  1. Overview
  2. Docs
On This Page
  1. Key-value store
package octez-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type
type 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.

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.

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