vsdb::basic::mapx

Struct Mapx

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

Expand description

A disk-based, HashMap-like data structure with typed keys and values.

Mapx stores key-value pairs on disk, encoding both keys and values for type safety and persistence.

§Key determinism

K must encode deterministically. Do not use HashMap, HashSet, or wrappers containing them as keys; their randomized iteration order can produce different storage bytes for logically equal keys.

Implementations§

Source §

impl<K, V> Mapx<K, V>
where K: KeyEnDe, V: ValueEnDe,

Source

pub unsafe fn shadow(&self) -> Self

§Safety

Creates a second handle to the same underlying storage, bypassing Rust’s aliasing guarantees. The caller must ensure no concurrent writes to the same key through any handle. Multiple writers on disjoint keys are safe. Concurrent reads alongside writes are safe (the engine provides snapshot isolation).

Source

pub unsafe fn from_bytes(s: impl AsRef<[u8]>) -> Self

§Safety

Reconstructs a handle from a raw byte slice that was previously produced by as_bytes on a valid instance of the same type. The caller must ensure s encodes a prefix they have unique ownership of. Passing arbitrary bytes (corrupted, truncated, or from a different type) is undefined behavior and may cause panics or silent data corruption on subsequent operations.

Source

pub fn instance_id(&self) -> u64

Returns the unique instance ID of this data structure.

Source

pub fn save_meta(&self) -> Result<u64>

Persists this instance’s metadata to disk so that it can be recovered later via from_meta.

Returns the instance_id that should be passed to from_meta.

Source

pub fn from_meta(instance_id: u64) -> Result<Self>

Recovers an instance from previously saved metadata.

The caller must ensure that the underlying VSDB database still contains the data referenced by this instance ID.

§Aliasing warning

The returned handle is a full alias of the original instance, not an independent copy — it addresses the exact same underlying key range (this is how instance_id is recovered: it is the raw prefix). If the original handle that produced this instance_id (or another from_meta/shadow restore of it) is still alive in-process, the same no-concurrent-writes-to-the-same-key discipline documented on shadow applies across every live alias: no concurrent writes to the same key through any handle. from_meta is intended to restore a handle after the original has gone out of scope (e.g. across a process restart); calling it while the original is still live requires the same care as shadow(), even though this function is safe Rust.

Source §

impl<K, V> Mapx<K, V>
where K: KeyEnDe, V: ValueEnDe,

Source

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

Retrieves a value from the map for a given key.

Source

pub fn get_mut(&mut self, key: &K) -> Option<ValueMut<'_, V>>

Retrieves a mutable reference to a value in the map.

Source

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

Checks if the map contains a value for the specified key.

Source

pub fn insert(&mut self, key: &K, value: &V)

Inserts a key-value pair into the map.

Does not return the old value for performance reasons.

Source

pub fn entry(&mut self, key: &K) -> Entry<'_, V>

Gets an entry for a given key, allowing for in-place modification.

Source

pub fn iter(&self) -> MapxIter<'_, K, V> ⓘ

Returns an iterator over the map’s entries.

Source

pub fn iter_mut(&mut self) -> MapxIterMut<'_, K, V> ⓘ

Returns a mutable iterator over the map’s entries.

Source

pub fn values(&self) -> MapxOrdValues<'_, V> ⓘ

Returns an iterator over the map’s values.

Source

pub fn values_mut(&mut self) -> MapxOrdValuesMut<'_, V> ⓘ

Returns a mutable iterator over the map’s values.

Source

pub fn remove(&mut self, key: &K)

Removes a key from the map.

Does not return the old value for performance reasons.

Source

pub fn batch_entry(&mut self) -> MapxBatchEntry<'_, K, V>

Start a batch operation.

This method allows you to perform multiple insert/remove operations and commit them atomically.

A failed commit consumes the buffered operations (none are applied) and is not retryable — re-stage the operations on a fresh batch instead.

§Examples

use vsdb::{Mapx, vsdb_set_base_dir};

vsdb_set_base_dir("/tmp/vsdb_mapx_batch_entry").unwrap();
let mut map = Mapx::new();

let mut batch = map.batch_entry();
batch.insert(&1, &"one".to_string());
batch.insert(&2, &"two".to_string());
batch.commit().unwrap();

assert_eq!(map.get(&1), Some("one".to_string()));
assert_eq!(map.get(&2), Some("two".to_string()));

Source

pub fn keys(&self) -> impl DoubleEndedIterator<Item = K> + '_

Returns an iterator over the map’s keys.

Decodes only K — unlike iter().map(|(k, _)| k), the value bytes are never decoded and discarded (see MapxOrdRawKey::keys’s doc comment for why this matters for nested-VSDB-collection value types).