Struct PersistentMap

pub struct PersistentMap<K, V, B>
where
    K: Eq + Hash + Clone + Serialize + DeserializeOwned + Send + Sync + 'static,
    V: Clone + Serialize + DeserializeOwned + Send + Sync + 'static,
    B: StorageBackend<K, V> + Send + Sync + 'static,
{ /* private fields */ }

A persistent key-value map with in-memory caching.

PersistentMap combines a fast in-memory DashMap with a persistent storage backend. It provides a simple API for storing and retrieving key-value pairs, with automatic persistence.

Type Parameters

• K: The key type, which must be hashable, serializable, and cloneable
• V: The value type, which must be serializable and cloneable
• B: The storage backend type, which must implement StorageBackend<K, V>

Examples

use persistent_map::{PersistentMap, Result};
use persistent_map::sqlite::SqliteBackend;

Implementations

impl<K, V, B> PersistentMap<K, V, B>

where K: Eq + Hash + Clone + Serialize + DeserializeOwned + Send + Sync + 'static, V: Clone + Serialize + DeserializeOwned + Send + Sync + 'static, B: StorageBackend<K, V> + Send + Sync + 'static,

pub async fn new(backend: B) -> Result<Self>

Creates a new PersistentMap with the given storage backend.

This method initializes the map and loads all existing key-value pairs from the storage backend into memory.

Examples

use persistent_map::{PersistentMap, Result};
use persistent_map::sqlite::SqliteBackend;

Errors

Returns an error if loading from the backend fails.

pub async fn load(&self) -> Result<(), PersistentError>

Loads all key-value pairs from the storage backend into memory.

This method is called automatically when creating a new PersistentMap, but can also be called manually to refresh the in-memory cache.

Examples

// Reload all data from the storage backend
map.load().await?;

Errors

Returns an error if loading from the backend fails.

pub async fn insert(&self, key: K, value: V) -> Result<Option<V>>

Inserts a key-value pair into the map and persists it to the storage backend.

If the map already contains the key, the value is updated and the old value is returned. Otherwise, None is returned.

Examples

// Insert a new key-value pair
let old = map.insert("key".to_string(), "value".to_string()).await?;
assert_eq!(old, None);

// Update an existing key
let old = map.insert("key".to_string(), "new value".to_string()).await?;
assert_eq!(old, Some("value".to_string()));

Errors

Returns an error if saving to the backend fails.

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

Retrieves a value from the map by its key.

This method only accesses the in-memory map and does not interact with the storage backend, making it very fast.

Examples

// Get a value
if let Some(value) = map.get(&"key".to_string()) {
    println!("Value: {}", value);
}

pub async fn remove(&self, key: &K) -> Result<Option<V>>

Removes a key-value pair from the map and the storage backend.

If the map contains the key, the key-value pair is removed and the old value is returned. Otherwise, None is returned.

Examples

// Remove a key-value pair
let old = map.remove(&"key".to_string()).await?;
if let Some(value) = old {
    println!("Removed value: {}", value);
}

Errors

Returns an error if deleting from the backend fails.

pub fn len(&self) -> usize

Returns the number of key-value pairs in the map.

Examples

let count = map.len();
println!("Map contains {} entries", count);

pub fn is_empty(&self) -> bool

Returns true if the map contains no key-value pairs.

Examples

if map.is_empty() {
    println!("Map is empty");
}

pub fn contains_key(&self, key: &K) -> bool

Returns true if the map contains the specified key.

Examples

if map.contains_key(&"key".to_string()) {
    println!("Map contains the key");
}

pub fn clear(&self)

Clears the in-memory map without affecting the storage backend.

This method only clears the in-memory cache and does not delete any data from the storage backend. To completely clear the storage, you should delete the underlying storage file or database.

Examples

// Clear the in-memory cache
map.clear();
assert_eq!(map.len(), 0);

pub async fn flush(&self) -> Result<(), PersistentError>

Flushes any buffered writes to the storage backend.

This method is useful for backends that buffer writes for performance. It ensures that all data is persisted to the storage medium.

Examples

// Ensure all data is persisted
map.flush().await?;

Errors

Returns an error if flushing the backend fails.

pub const fn backend(&self) -> &B

Returns a reference to the storage backend.

This method is useful for accessing backend-specific functionality.

Examples

let backend = map.backend();
// Use backend-specific functionality