kvstore_v1_xxx Namespace Reference

The kv store namespace. More...

Namespaces
	traits
	Traits.

Classes
struct	basic_key_value_store_info
	Information about an available key value store implementation. More...
class	basic_key_value_store
	A possibly hardware-implemented basic key-value store. More...

Typedefs
template<class T >
using	span = llfio::span< T >
template<class T >
using	result = llfio::result< T >

Enumerations
enum class	kvstore_errc {   success = 0 , invalid_uri , unsupported_uri , unsupported_integrity ,   transaction_aborted_collision }

Functions
result< basic_key_value_store >	create_kvstore (const basic_key_value_store::uri_type &uri, basic_key_value_store::size_type key_size, basic_key_value_store::features _features, basic_key_value_store::mode _mode=basic_key_value_store::mode::write, basic_key_value_store::creation _creation=basic_key_value_store::creation::if_needed, basic_key_value_store::caching _caching=basic_key_value_store::caching::all)
	Create a new key value store, or open or truncate an existing key value store, using the given URI. More...
result< basic_key_value_store >	open_kvstore (const basic_key_value_store::uri_type &uri, basic_key_value_store::mode _mode=basic_key_value_store::mode::write, basic_key_value_store::caching _caching=basic_key_value_store::caching::all)
	Open an existing key value store. A convenience overload for create_kvstore().
result< span< basic_key_value_store_info > >	enumerate_kvstores (span< basic_key_value_store_info > lst)
	Fill an array with information about all the key value stores available to this process.

Detailed Description

The kv store namespace.

Enumeration Type Documentation

kvstore_errc

enum kvstore_v1_xxx::kvstore_errc

strong

The error codes specific to basic_key_value_store. Note the std::errc equivalent codes may also be returned e.g. std::errc::insufficient_disk_space.

Enumerator
invalid_uri	The URI is not in an understood format.
unsupported_uri	The URI specified an unsupported scheme or mechanism.
unsupported_integrity	The requested integrity level is not available for this device URI.
transaction_aborted_collision	The transaction could not be committed due to dependent key update.

{
  success = 0,
  invalid_uri,                    //!< The URI is not in an understood format.
  unsupported_uri,                //!< The URI specified an unsupported scheme or mechanism.
  unsupported_integrity,          //!< The requested integrity level is not available for this device URI.
  transaction_aborted_collision,  //!< The transaction could not be committed due to dependent key update.
};

Function Documentation

create_kvstore()

result<basic_key_value_store> kvstore_v1_xxx::create_kvstore ( const basic_key_value_store::uri_type &  uri, basic_key_value_store::size_type  key_size, basic_key_value_store::features  _features, basic_key_value_store::mode  _mode = basic_key_value_store::mode::write, basic_key_value_store::creation  _creation = basic_key_value_store::creation::if_needed, basic_key_value_store::caching  _caching = basic_key_value_store::caching::all  )

inline

Create a new key value store, or open or truncate an existing key value store, using the given URI.

Query the system and/or process registry of key value store providers for an implementation capable of using a store at uri with the specified key size and features. Guaranteed built-in providers are:

• file:// based providers:

  • directory_simple_legacy: A very simple FAT-compatible file based store based on turning the key into hexadecimal, chopping it into chunks of four (0x0000 - 0xffff) such that a hex key 0x01234567890abcdef's value would be stored in the path store/01234/5678/90ab/cdef. Key updates are first written into stage/01234/5678/90ab/cdef, then once fully written they are atomically renamed into store. This store implements only features::stable_values, and is very widely compatible, including with networked drives. Its major downside is potential allocation wastage for many small sized values too big to be stored in the inode, but substantially below the allocation granularity.
  • directory_modern: A much more complex file based store which implements features::history, features::stable_values, features::stable_keys, features::update_deltas, features::atomic_snapshots and features::atomic_transactions.

  Inside the file monotonic is a 64 bit monotonic count representing time. Updated values are kept at store/01234/5678/90ab/cdef/values/count, where the monotonic count is atomically incremented every update. store/01234/5678/90ab/cdef/deltas is where 4Kb update deltas are kept if the value is larger than 64Kb. store/01234/5678/90ab/cdef/latest is the count of the latest value, its size, and if deltas need to be applied.

  • single_file: Initially all keys and values are kept in memory. Upon first URI fetch after first creation, a single file is created comprising all the keys and values associatively mapped. This single file can be then be mapped as shared memory into multiple processes, thus enabling multiple concurrent C++ programs to collaborate on a shared store where only values are mutable (and not resizeable). Only one process may pin a value at a time concurrently.

URIs may of course specify other sources of key value store than on the file system. Third parties may have registered system-wide implementations available to all programs. The local process may have registered additional implementations as well.