Oveview

Lightweight, persistent key-value store. Main docs: https://pigweed.dev/pw_kvs.

Namespaces
namespace	pw
	The Pigweed namespace.

namespace	pw::kvs
	Lightweight key-value store library.

Classes
struct	pw::kvs::Options

class	pw::kvs::KeyValueStore

class	pw::kvs::KeyValueStore::Item
	Representation of a key-value entry during iteration. More...

class	pw::kvs::KeyValueStore::iterator
	Supported iteration methods. More...

struct	pw::kvs::KeyValueStore::StorageStats

class	pw::kvs::KeyValueStoreBuffer< kMaxEntries, kMaxUsableSectors, kRedundancy, kEntryFormats >

Macros
#define	PW_KVS_LOG_LEVEL PW_LOG_LEVEL_INFO

#define	PW_KVS_MAX_FLASH_ALIGNMENT 256UL

#define	PW_KVS_REMOVE_DELETED_KEYS_IN_HEAVY_MAINTENANCE 1

Typedefs
using	pw::kvs::KeyValueStore::const_iterator = iterator

using	pw::kvs::KeyValueStore::Address = FlashPartition::Address

using	pw::kvs::KeyValueStore::Entry = internal::Entry

using	pw::kvs::KeyValueStore::KeyDescriptor = internal::KeyDescriptor

using	pw::kvs::KeyValueStore::SectorDescriptor = internal::SectorDescriptor

Enumerations
enum class	GargbageCollectOnWrite { kDisabled , kOneSector , kAsManySectorsNeeded }

enum class	ErrorRecovery { kImmediate , kLazy , kManual }

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

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

StatusWithSize	pw::kvs::KeyValueStore::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	pw::kvs::KeyValueStore::Get (const std::string_view &key, const Pointer &pointer) const

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)

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

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

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

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

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

void	pw::kvs::KeyValueStore::LogDebugInfo () const

const char *	pw::kvs::KeyValueStore::Item::key () const

StatusWithSize	pw::kvs::KeyValueStore::Item::Get (span< std::byte > value_buffer, size_t offset_bytes=0) const

template<typename Pointer , typename = std::enable_if_t<std::is_pointer<Pointer>::value>>
Status	pw::kvs::KeyValueStore::Item::Get (const Pointer &pointer) const

StatusWithSize	pw::kvs::KeyValueStore::Item::ValueSize () const

iterator &	pw::kvs::KeyValueStore::iterator::operator++ ()
	Increments to the next key-value entry in the container.

iterator	pw::kvs::KeyValueStore::iterator::operator++ (int)
	Increments to the next key-value entry in the container.

const Item &	pw::kvs::KeyValueStore::iterator::operator* ()
	Reads the entry's key from flash.

const Item *	pw::kvs::KeyValueStore::iterator::operator-> ()
	Reads the entry into the `Item` object.

constexpr bool	pw::kvs::KeyValueStore::iterator::operator== (const iterator &rhs) const
	Equality comparison of two entries.

constexpr bool	pw::kvs::KeyValueStore::iterator::operator!= (const iterator &rhs) const
	Inequality comparison of two entries.

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

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

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

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

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

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

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

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

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

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

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

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

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

	pw::kvs::KeyValueStore::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)

	pw::kvs::KeyValueStoreBuffer< kMaxEntries, kMaxUsableSectors, kRedundancy, kEntryFormats >::KeyValueStoreBuffer (FlashPartition *partition, const EntryFormat &format, const Options &options={})

	pw::kvs::KeyValueStoreBuffer< kMaxEntries, kMaxUsableSectors, kRedundancy, kEntryFormats >::KeyValueStoreBuffer (FlashPartition *partition, span< const EntryFormat, kEntryFormats > formats, const Options &options={})

Variables
GargbageCollectOnWrite	pw::kvs::Options::gc_on_write

ErrorRecovery	pw::kvs::Options::recovery = ErrorRecovery::kLazy

bool	pw::kvs::Options::verify_on_read = true

bool	pw::kvs::Options::verify_on_write = true

size_t	pw::kvs::KeyValueStore::StorageStats::writable_bytes

size_t	pw::kvs::KeyValueStore::StorageStats::in_use_bytes
	The number of bytes in the KVS that are already in use.

size_t	pw::kvs::KeyValueStore::StorageStats::reclaimable_bytes

size_t	pw::kvs::KeyValueStore::StorageStats::sector_erase_count
	The total count of individual sector erases that have been performed.

size_t	pw::kvs::KeyValueStore::StorageStats::corrupt_sectors_recovered
	The number of corrupt sectors that have been recovered.

size_t	pw::kvs::KeyValueStore::StorageStats::missing_redundant_entries_recovered

size_t	pw::kvs::KeyValueStore::InternalStats::sector_erase_count

size_t	pw::kvs::KeyValueStore::InternalStats::corrupt_sectors_recovered

size_t	pw::kvs::KeyValueStore::InternalStats::missing_redundant_entries_recovered

constexpr size_t	pw::kvs::kMaxFlashAlignment = 256UL

Friends
class	pw::kvs::KeyValueStore::Item::iterator

class	pw::kvs::KeyValueStore::iterator::KeyValueStore

Macro Definition Documentation

◆ PW_KVS_LOG_LEVEL

#define PW_KVS_LOG_LEVEL PW_LOG_LEVEL_INFO

Which log level to use for pw_kvs logs.

◆ PW_KVS_MAX_FLASH_ALIGNMENT

#define PW_KVS_MAX_FLASH_ALIGNMENT 256UL

The maximum flash alignment supported.

◆ PW_KVS_REMOVE_DELETED_KEYS_IN_HEAVY_MAINTENANCE

#define PW_KVS_REMOVE_DELETED_KEYS_IN_HEAVY_MAINTENANCE 1

Whether to remove deleted keys in heavy maintanence. This feature costs some code size (>1KB) and is only necessary if arbitrary key names are used. Without this feature, deleted key entries can fill the KVS, making it impossible to add more keys, even though most keys are deleted.

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/3]

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/3]

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

inline

Returns: The value referred to by this iterator. Equivalent to pw::kvs::KeyValueStore::Get().

◆ Get() [3/3]

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

◆ key()

const char * pw::kvs::KeyValueStore::Item::key ( ) const

inline

Returns: The key as a null-terminated string.

◆ 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.
* 
*

Variable Documentation

◆ gc_on_write

GargbageCollectOnWrite pw::kvs::Options::gc_on_write

Initial value:

=

GargbageCollectOnWrite::kAsManySectorsNeeded

◆ missing_redundant_entries_recovered

size_t pw::kvs::KeyValueStore::StorageStats::missing_redundant_entries_recovered

The number of missing redundant copies of entries that have been recovered.

◆ reclaimable_bytes

size_t pw::kvs::KeyValueStore::StorageStats::reclaimable_bytes

The maximum number of bytes possible to reclaim by garbage collection. The number of bytes actually reclaimed by maintenance depends on the type of maintenance that's performed.

◆ writable_bytes

size_t pw::kvs::KeyValueStore::StorageStats::writable_bytes

The number of writeable bytes remaining in the KVS. This number doesn't include the one empty sector required for KVS garbage collection.

Oveview

Namespaces

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Friends

Macro Definition Documentation

◆ PW_KVS_LOG_LEVEL

◆ PW_KVS_MAX_FLASH_ALIGNMENT

◆ PW_KVS_REMOVE_DELETED_KEYS_IN_HEAVY_MAINTENANCE

Function Documentation

◆ begin()

◆ CheckForErrors()

◆ Delete()

◆ empty()

◆ end()

◆ error_detected()

◆ FullMaintenance()

◆ Get() [1/3]

◆ Get() [2/3]

◆ Get() [3/3]

◆ GetStorageStats()

◆ HeavyMaintenance()

◆ Init()

◆ key()

◆ 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()

Variable Documentation

◆ gc_on_write

◆ missing_redundant_entries_recovered

◆ reclaimable_bytes

◆ writable_bytes