Struct PersistentKeyValueStore

pub struct PersistentKeyValueStore<K, V> { /* private fields */ }

Implementations

impl<K, V> PersistentKeyValueStore<K, V>

where K: Serializable,

pub fn new(path: impl AsRef<Path>, config: Config) -> Result<Self>

Constructs a new store instance. The store will be backed by the given path and use the provided configuration. This function will block on restoring previously saved state from disk.

Only one store instance can be alive at a time for a given path.

Iterators

The store acts like a collection and supports (read-only) Iterator but does not support any mutating collection traits (e.g. FromIterator or Extend). This is needed since set() is fallible.

A consuming iterator consumes the in-memory store only, not the on-disk data.

Example

use persistent_kv::{Config, PersistentKeyValueStore};
let path = "/tmp/mystore1";
let store: PersistentKeyValueStore<String, String> =
    PersistentKeyValueStore::new(path, Config::default())?;
store.set("foo", "1")?;
// Drop the first store instance to ensure no two instances are alive.
drop(store);
// Second instance constructed from same path recovers the data.
let store: PersistentKeyValueStore<String, String> =
    PersistentKeyValueStore::new(path, Config::default())?;
assert_eq!(store.get("foo"), Some("1".to_string()));

Errors

Propagates IO errors when reading from disk, also fails when the snapshot files don’t follow the exact naming schema expected (and written) by this crate.

pub fn unset<Q>(&self, key: &Q) -> Result<()>

where K: Borrow<Q>, Q: ?Sized + Serializable,

Removes a key from the store. Supports using borrowed keys (e.g. str for a String key).

Example

use persistent_kv::{Config, PersistentKeyValueStore};
let store: PersistentKeyValueStore<String, String> =
    PersistentKeyValueStore::new("/tmp/mystore2", Config::default())?;
store.set("foo", "1")?;
assert_eq!(store.get("foo"), Some("1".to_string()));
store.unset("foo")?;
assert_eq!(store.get("foo"), None);

Errors

Propagates any IO errors that occur directly as a result of the write operation.

impl<K, V> PersistentKeyValueStore<K, V>

where K: Serializable, V: Deserializable + Serializable,

Store methods for simple values: Vecu8, String, integers. We bypass all serialization frameworks for these types.

pub fn set(&self, key: impl Into<K>, value: impl Into<V>) -> Result<()>

Sets a key-value pair in the store. If the key already exists, the value will be overwritten.

Example

use persistent_kv::{Config, PersistentKeyValueStore};
let store: PersistentKeyValueStore<String, String> =
   PersistentKeyValueStore::new("/tmp/mystore3", Config::default())?;
store.set("foo", "1")?;
assert_eq!(store.get("foo"), Some("1".to_string()));

Errors

Propagates any IO errors that occur directly as a result of the write operation.

pub fn get<Q>(&self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: ?Sized + Serializable,

Retrieves a value from the store. Supports lookups using borrowed keys (e.g. str for a String key).

Example

use persistent_kv::{Config, PersistentKeyValueStore};
let store: PersistentKeyValueStore<String, String> =
   PersistentKeyValueStore::new("/tmp/mystore4", Config::default())?;
store.set("foo", "1")?;
assert_eq!(store.get("foo"), Some("1".to_string()));

impl<K, V> PersistentKeyValueStore<K, V>

where K: Serializable, V: Message + Default,

Store version for protobuf values.

pub fn set_proto(&self, key: impl Into<K>, value: impl Message) -> Result<()>

Sets a protobuf-coded value in the store. If the key already exists, the value will be overwritten.

Example

use prost::Message;
use persistent_kv::{Config, PersistentKeyValueStore};
#[derive(Clone, PartialEq, Message)]
pub struct Foo {
    #[prost(uint32, tag = "1")]
    pub bar: u32,
}
let store: PersistentKeyValueStore<String, Foo> =
   PersistentKeyValueStore::new("/tmp/mystore5", Config::default())?;
store.set_proto("foo", Foo {bar: 42})?;
assert_eq!(store.get_proto("foo")?, Some(Foo {bar: 42}));

Errors

Propagates any IO errors that occur directly as a result of the write operation.

pub fn get_proto<Q>(&self, key: &Q) -> Result<Option<V>, DecodeError>

where K: Borrow<Q>, Q: ?Sized + Serializable,

Retrieves a protobuf-coded value from the store. Supports lookups using borrowed keys (e.g. str for a String key).

Example

use prost::Message;
use persistent_kv::{Config, PersistentKeyValueStore};
#[derive(Clone, PartialEq, Message)]
pub struct Foo {
    #[prost(uint32, tag = "1")]
    pub bar: u32,
}
let store: PersistentKeyValueStore<String, Foo> =
   PersistentKeyValueStore::new("/tmp/mystore6", Config::default())?;
store.set_proto("foo", Foo {bar: 42})?;
assert_eq!(store.get_proto("foo")?, Some(Foo {bar: 42}));

Errors

Forwards proto decode errors.

impl<K, V> PersistentKeyValueStore<K, V>

where K: Deserializable + Serializable, V: Deserializable + Serializable,

pub fn iter<'a>(&'a self) -> Box<dyn Iterator<Item = (K, V)> + 'a>

Trait Implementations

impl<K, V> Debug for PersistentKeyValueStore<K, V>

Debug trait for PersistentKeyValueStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, K, V> IntoIterator for &'a PersistentKeyValueStore<K, V>

where K: Deserializable + Serializable, V: Deserializable + Serializable,

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = <&'a PersistentKeyValueStore<K, V> as IntoIterator>::Item> + 'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V> IntoIterator for PersistentKeyValueStore<K, V>

where K: Deserializable + Serializable, V: Deserializable + Serializable,

Implement IntoIterator for PersistentKeyValueStore and for &PersistentKeyValueStore using the underlying store’s implementation, encoding/decoding keys and values as needed.

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = <PersistentKeyValueStore<K, V> as IntoIterator>::Item>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V> Send for PersistentKeyValueStore<K, V>

impl<K, V> Sync for PersistentKeyValueStore<K, V>