#include <key_value_store.h>

Inheritance diagram for pw::kvs::KeyValueStore:

Classes
class	Item
	Representation of a key-value entry during iteration. More...

class	iterator
	Supported iteration methods. More...

struct	StorageStats

Public Types
using	const_iterator = iterator

Public Member Functions
Status	Init ()

bool	initialized () const

StatusWithSize	Get (std::string_view key, span< std::byte > value, size_t offset_bytes=0) const

template<typename Pointer , typename = std::enable_if_t<std::is_pointer<Pointer>::value>>
Status	Get (const std::string_view &key, const Pointer &pointer) const

template<typename T , typename std::enable_if_t< ConvertsToSpan< T >::value > * = nullptr>
Status	Put (const std::string_view &key, const T &value)

template<typename T , typename std::enable_if_t<!ConvertsToSpan< T >::value > * = nullptr>
Status	Put (const std::string_view &key, const T &value)

Status	Delete (std::string_view key)

StatusWithSize	ValueSize (std::string_view key) const

Status	HeavyMaintenance ()

Status	FullMaintenance ()

Status	PartialMaintenance ()

void	LogDebugInfo () const

iterator	begin () const

iterator	end () const

size_t	size () const

size_t	total_entries_with_deleted () const

size_t	max_size () const

size_t	empty () const

uint32_t	transaction_count () const

StorageStats	GetStorageStats () const

size_t	redundancy () const

bool	error_detected () const

size_t	max_key_value_size_bytes () const

bool	CheckForErrors ()

Static Public Member Functions
static constexpr size_t	max_key_value_size_bytes (size_t partition_sector_size_bytes)

Protected Types
using	Address = FlashPartition::Address

using	Entry = internal::Entry

using	KeyDescriptor = internal::KeyDescriptor

using	SectorDescriptor = internal::SectorDescriptor

Protected Member Functions
	KeyValueStore (FlashPartition partition, span< const EntryFormat > formats, const Options &options, size_t redundancy, Vector< SectorDescriptor > &sector_descriptor_list, const SectorDescriptor temp_sectors_to_skip, Vector< KeyDescriptor > &key_descriptor_list, Address addresses)

Detailed Description

Flash-backed persistent key-value store (KVS) with integrated wear-leveling.

Instances are declared as instances of pw::kvs::KeyValueStoreBuffer<MAX_ENTRIES, MAX_SECTORS>, which allocates buffers for tracking entries and flash sectors.

#include "pw_kvs/key_value_store.h"
#include "pw_kvs/flash_test_partition.h"
 
constexpr size_t kMaxSectors = 6;
constexpr size_t kMaxEntries = 64;
static constexpr pw::kvs::EntryFormat kvs_format = {
  .magic = 0xd253a8a9,  // Prod apps should use a random number here
  .checksum = nullptr
};
pw::kvs::KeyValueStoreBuffer<kMaxEntries, kMaxSectors> kvs(
  &pw::kvs::FlashTestPartition(),
  kvs_format
);
 
kvs.Init();

Member Function Documentation

◆ begin()

iterator pw::kvs::KeyValueStore::begin ( ) const

Returns: The first key-value entry in the container. Used for iteration.

◆ CheckForErrors()

bool pw::kvs::KeyValueStore::CheckForErrors ( )

Checks the KVS for any error conditions and returns true if any errors are present. Primarily intended for test and internal use.

◆ Delete()

Status pw::kvs::KeyValueStore::Delete ( std::string_view key )

Removes a key-value entry from the KVS.

Parameters

[in] key - The name of the key-value entry to delete.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The entry was successfully deleted.
* 
*     NOT_FOUND: ``key`` is not present in the KVS.
* 
*     DATA_LOSS: Checksum validation failed after recording the
*     erase.
* 
*     RESOURCE_EXHAUSTED: Insufficient space to mark the entry as deleted.
* 
*     FAILED_PRECONDITION: The KVS is not initialized. Call ``Init()``
*     before calling this method.
* 
*     INVALID_ARGUMENT: ``key`` is empty or too long.
* 
*

◆ empty()

size_t pw::kvs::KeyValueStore::empty ( ) const

inline

Returns: true if the KVS is empty.

◆ end()

iterator pw::kvs::KeyValueStore::end ( ) const

inline

Returns: The last key-value entry in the container. Used for iteration.

◆ error_detected()

bool pw::kvs::KeyValueStore::error_detected ( ) const

inline

Returns: true if the KVS has any unrepaired errors.

◆ FullMaintenance()

Status pw::kvs::KeyValueStore::FullMaintenance ( )

inline

Perform all maintenance possible, including all needed repairing of corruption and garbage collection of reclaimable space in the KVS. When configured for manual recovery, this (along with HeavyMaintenance()) is the only way KVS repair is triggered.

Does not garbage collect sectors with valid data unless the KVS is mostly full.

◆ Get() [1/2]

template<typename Pointer , typename = std::enable_if_t<std::is_pointer<Pointer>::value>>

Status pw::kvs::KeyValueStore::Get	(	const std::string_view &	key,
		const Pointer &	pointer
	)		const

inline

Overload of Get() that accepts a pointer to a trivially copyable object.

If value is an array, call Get() with as_writable_bytes(span(array)), or pass a pointer to the array instead of the array itself.

◆ Get() [2/2]

StatusWithSize pw::kvs::KeyValueStore::Get	(	std::string_view	key,
		span< std::byte >	value,
		size_t	offset_bytes = `0`
	)		const

Reads the value of an entry in the KVS. The value is read into the provided buffer and the number of bytes read is returned. Reads can be started at an offset.

Parameters

[in]	key	The name of the key.
[out]	value	The buffer to read the key's value into.
[in]	offset_bytes	The byte offset to start the read at. Optional.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The entry was successfully read.
* 
*     NOT_FOUND: The key is not present in the KVS.
* 
*     DATA_LOSS: Found the entry, but the data was corrupted.
* 
*     RESOURCE_EXHAUSTED: The buffer could not fit the entire
*     value, but as many bytes as possible were written to it. The number of
*     of bytes read is returned. The remainder of the value can be read by
*     calling ``Get()`` again with an offset.
* 
*     FAILED_PRECONDITION: The KVS is not initialized. Call ``Init()``
*     before calling this method.
* 
*     INVALID_ARGUMENT: ``key`` is empty or too long, or ``value``
*     is too large.
* 
*

◆ GetStorageStats()

StorageStats pw::kvs::KeyValueStore::GetStorageStats ( ) const

Returns: A StorageStats struct with details about the current and past state of the KVS.

◆ HeavyMaintenance()

Status pw::kvs::KeyValueStore::HeavyMaintenance ( )

inline

Performs all maintenance possible, including all needed repairing of corruption and garbage collection of reclaimable space in the KVS. When configured for manual recovery, this (along with FullMaintenance()) is the only way KVS repair is triggered.

Warning: Performs heavy garbage collection of all reclaimable space, regardless of whether there's other valid data in the sector. This method may cause a significant amount of moving of valid entries.

◆ Init()

Status pw::kvs::KeyValueStore::Init ( )

Initializes the KVS. Must be called before calling other functions.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The KVS successfully initialized.
* 
*     DATA_LOSS: The KVS initialized and is usable, but contains corrupt
*     data.
* 
*     UNKNOWN: Unknown error. The KVS is not initialized.
* 
*

◆ max_key_value_size_bytes() [1/2]

size_t pw::kvs::KeyValueStore::max_key_value_size_bytes ( ) const

inline

Returns: The maximum number of bytes allowed for a key-value combination.

◆ max_key_value_size_bytes() [2/2]

static constexpr size_t pw::kvs::KeyValueStore::max_key_value_size_bytes ( size_t partition_sector_size_bytes )

inlinestaticconstexpr

Returns: The maximum number of bytes allowed for a given sector size for a key-value combination.

◆ max_size()

size_t pw::kvs::KeyValueStore::max_size ( ) const

inline

Returns: The maximum number of KV entries that's possible in the KVS.

◆ PartialMaintenance()

Status pw::kvs::KeyValueStore::PartialMaintenance ( )

Performs a portion of KVS maintenance. If configured for at least lazy recovery, will do any needed repairing of corruption. Does garbage collection of part of the KVS, typically a single sector or similar unit that makes sense for the KVS implementation.

◆ Put()

template<typename T , typename std::enable_if_t< ConvertsToSpan< T >::value > * = nullptr>

Status pw::kvs::KeyValueStore::Put	(	const std::string_view &	key,
		const T &	value
	)

inline

Adds a key-value entry to the KVS. If the key was already present, its value is overwritten.

Parameters

[in]	key	The name of the key. All keys in the KVS must have a unique hash. If the hash of your key matches an existing key, nothing is added and embed:rst:inline :c:enumerator:`ALREADY_EXISTS` is returned.
[in]	value	The value for the key. This can be a span of bytes or a trivially copyable object.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The entry was successfully added or updated.
* 
*     DATA_LOSS: Checksum validation failed after writing data.
* 
*     RESOURCE_EXHAUSTED: Not enough space to add the entry.
* 
*     ALREADY_EXISTS: The entry could not be added because a different
*     key with the same hash is already in the KVS.
* 
*     FAILED_PRECONDITION: The KVS is not initialized. Call ``Init()``
*     before calling this method.
* 
*     INVALID_ARGUMENT: ``key`` is empty or too long, or ``value``
*     is too large.
* 
*

◆ redundancy()

size_t pw::kvs::KeyValueStore::redundancy ( ) const

inline

Returns: The number of identical copies written for each entry. A redundancy of 1 means that only a single copy is written for each entry.

◆ size()

size_t pw::kvs::KeyValueStore::size ( ) const

inline

Returns: The number of valid entries in the KVS.

◆ total_entries_with_deleted()

size_t pw::kvs::KeyValueStore::total_entries_with_deleted ( ) const

inline

Returns: The number of valid entries and deleted entries yet to be collected.

◆ transaction_count()

uint32_t pw::kvs::KeyValueStore::transaction_count ( ) const

inline

Returns: The number of transactions that have occurred since the KVS was first used. This value is retained across initializations, but is reset if the underlying flash is erased.

◆ ValueSize()

StatusWithSize pw::kvs::KeyValueStore::ValueSize ( std::string_view key ) const

Returns the size of the value corresponding to the key.

Parameters

[in] key - The name of the key.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The size was returned successfully.
* 
*     NOT_FOUND: ``key`` is not present in the KVS.
* 
*     DATA_LOSS: Checksum validation failed after reading the entry.
* 
*     FAILED_PRECONDITION: The KVS is not initialized. Call ``Init()``
*     before calling this method.
* 
*     INVALID_ARGUMENT: ``key`` is empty or too long.
* 
*

The documentation for this class was generated from the following file:

pw_kvs/public/pw_kvs/key_value_store.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ CheckForErrors()

◆ Delete()

◆ empty()

◆ end()

◆ error_detected()

◆ FullMaintenance()

◆ Get() [1/2]

◆ Get() [2/2]

◆ GetStorageStats()

◆ HeavyMaintenance()

◆ Init()

◆ max_key_value_size_bytes() [1/2]

◆ max_key_value_size_bytes() [2/2]

◆ max_size()

◆ PartialMaintenance()

◆ Put()

◆ redundancy()

◆ size()

◆ total_entries_with_deleted()

◆ transaction_count()

◆ ValueSize()