Struct VarTypedMap 

pub struct VarTypedMap<K: Key + Send + Sync + Hash + Eq, T: Send + Sync, C: Codec<T> + Clone, H: TypedWriteHook<K, T> = NoHook> { /* private fields */ }

A map with fixed-size keys and typed values T. Values are encoded via a Codec and stored on disk (variable length), with a block cache (≤ 8 KB values) and a value cache (> 8 KB values) for reads. Uses per-shard HashMap for O(1) lookup. Ordered scans are available when opened with iterable(true) via iter_view. Use VarTypedTree for prefix/range scans without the iterable flag.

Thin wrapper around VarMap<K, VarTypedHookAdapter<K, T, C, H>>.

Error handling

Same convention as VarTypedTree: get returns None on decode errors. migrate keeps entries that fail to decode.

Write hooks

Uses TypedWriteHook<K, T> via [VarTypedHookAdapter]. The hook receives &T directly; the adapter decodes raw bytes via the codec. on_write fires on put/insert/delete/cas/compare_delete/update/fetch_update and inside atomic().

Implementations

impl<K: Key + Send + Sync + Hash + Eq, T: Send + Sync, C: Codec<T> + Clone> VarTypedMap<K, T, C>

pub fn open(path: impl AsRef<Path>, config: Config, codec: C) -> DbResult<Self>

Open or create a VarTypedMap at the given path.

impl<K: Key + Send + Sync + Hash + Eq, T: Send + Sync, C: Codec<T> + Clone, H: TypedWriteHook<K, T>> VarTypedMap<K, T, C, H>

pub fn open_hooked( path: impl AsRef<Path>, config: Config, codec: C, hook: H, ) -> DbResult<Self>

Open or create a VarTypedMap with a typed write hook.

pub fn clean_shutdown(&self) -> DbResult<()>

Graceful shutdown: write hint files (if enabled), flush write buffers + fsync.

pub fn close(self) -> DbResult<()>

pub fn flush_buffers(&self) -> DbResult<()>

Flush all shard write buffers to disk (without fsync).

pub fn config(&self) -> &Config

Get the database configuration.

pub fn compact(&self) -> DbResult<usize>

Trigger a compaction pass across all shards.

pub fn sync_hints(&self) -> DbResult<()>

Write hint files for all active shard files. Call during graceful shutdown.

pub fn warmup(&self) -> DbResult<()>

Pre-populate the block cache with blocks containing live values.

pub fn as_inner(&self) -> &VarMap<K, VarTypedHookAdapter<K, T, C, H>>

Access the underlying VarMap.

pub fn codec(&self) -> &C

Access the codec used for encoding / decoding values.

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

Get and decode a value by key. Returns None if absent or undecodable. O(1) average index lookup under a brief per-shard mutex; the pread on a cache miss runs outside the lock, then decode.

pub fn get_or_err(&self, key: &K) -> DbResult<T>

Get a value by key, returning Err(KeyNotFound) if absent or Err(CorruptedEntry) if present but undecodable.

pub fn try_get(&self, key: &K) -> DbResult<Option<T>>

Strict read: Ok(None) only when absent; Err when present but the value cannot be read or decoded.

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

pub fn for_each(&self, f: impl FnMut(K, T))

Read-only pass over all live entries, decoding each value. Order is unspecified — intended for schema validation on a quiet database. Entries whose value fails to decode are skipped (logged at debug), matching VarTypedTree::iter / VarTypedMap::get.

pub fn iter_view(&self) -> Option<VarTypedMapIterView<'_, K, T, C, H>>

Ordered scan view. None unless the collection was opened with iterable(true). Direction follows Config::reversed (default DESC).

Occasional admin/maintenance API, not a hot path. Use it to browse a collection or bulk-clean stale rows (retain); for scan-heavy access reach for the *Tree sibling — a Map’s strength is O(1) point lookup, and the companion key index costs extra memory plus O(log N) per write. Unlike a Tree scan it is not a point-in-time snapshot: the k-way merge drops each shard lock between batches, so concurrent writes may be only partially reflected (run on a quiet DB if you need a coherent view).

pub fn put(&self, key: &K, value: &T) -> DbResult<bool>

Insert or update a key-value pair.

Returns true if a previous value for key existed (overwrite), false for a fresh insert.

pub fn insert(&self, key: &K, value: &T) -> DbResult<()>

pub fn delete(&self, key: &K) -> DbResult<bool>

pub fn cas(&self, key: &K, expected: &T, new_value: &T) -> DbResult<()>

pub fn compare_delete(&self, key: &K, expected: &T) -> DbResult<()>

Compare-and-delete based on encoded bytes. Relies on deterministic codec output. Returns Ok(()) on success, Err(CasMismatch) if current != expected, Err(KeyNotFound) if the key doesn’t exist.

pub fn update(&self, key: &K, f: impl FnOnce(&T) -> T) -> DbResult<Option<T>>

pub fn fetch_update( &self, key: &K, f: impl FnOnce(&T) -> T, ) -> DbResult<Option<T>>

pub fn atomic<R>( &self, shard_key: &K, f: impl FnOnce(&mut VarTypedMapShard<'_, K, T, C, H>) -> DbResult<R>, ) -> DbResult<R>

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn shard_for(&self, key: &K) -> usize

pub fn entry_len(&self, key: &K) -> Option<u32>

Encoded value byte length for key, or None if absent. Reads only the in-memory index entry (DiskLoc::len); no disk I/O.

pub fn migrate(&self, f: impl Fn(&K, &T) -> MigrateAction<T>) -> DbResult<usize>

Trait Implementations

impl<T, C, H> Collection for VarTypedMap<T::SelfId, T, C, H>

where T: CollectionMeta + Send + Sync, C: Codec<T> + Clone + 'static, H: TypedWriteHook<T::SelfId, T>, T::SelfId: Key + Send + Sync + Hash + Eq,

Available on crate feature armour only.

fn name(&self) -> &str

Collection name (from CollectionMeta::NAME).

fn len(&self) -> usize

Number of entries in the collection.

fn compact(&self) -> DbResult<usize>

Run a compaction pass across all shards.

fn flush(&self) -> DbResult<()>

Flush in-memory write buffers and pending hint data so an immediate process exit will not lose committed writes. No default — every impl must provide this to avoid silent durability gaps.

fn periodic_flush(&self) -> DbResult<()>

Lightest operation that bounds the periodic durability window for background use. Backend-specific:

fn clean_shutdown(&self) -> DbResult<()>

Full clean shutdown for this collection. Heavier than flush:

fn is_empty(&self) -> bool

impl<K: Key + Send + Sync + Hash + Eq, T: Send + Sync, C: Codec<T> + Clone, H: TypedWriteHook<K, T>> CompactionIndex<K> for VarTypedMap<K, T, C, H>

fn update_if_match(&self, key: &K, old_loc: DiskLoc, new_loc: DiskLoc) -> bool

If the current index points to old_loc, it is updated to new_loc and returns true.

fn invalidate_blocks(&self, shard_id: u8, file_id: u32, total_bytes: u64)

Invalidate cached blocks for a file after compaction replaces its contents.

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

Returns true if the key currently exists in the index (i.e. has a live Put).

fn is_live(&self, shard_id: u8, key: &K, loc: DiskLoc) -> bool

Returns true iff the index currently maps key to exactly loc — i.e. the entry at loc is the live (latest) version of key.

impl<T, C, H> IndexTarget for VarTypedMap<T::SelfId, T, C, H>

where T: CollectionMeta + GetRefs + Send + Sync + 'static, T::SelfId: Key + GetRefs + GetType + Hash + Eq + Send + Sync + 'static, C: Codec<T> + Clone + Send + Sync + 'static, H: TypedWriteHook<T::SelfId, T> + 'static,

Available on crate feature var-collections only.

fn put_entry(&self, k: &Self::K, v: &Self::V) -> DbResult<()>

fn delete_entry(&self, k: &Self::K) -> DbResult<()>

impl<K, T, C, H> MultiTx for VarTypedMap<K, T, C, H>

where K: Key + Send + Sync + Hash + Eq, T: Send + Sync, C: Codec<T> + Clone, H: TypedWriteHook<K, T>,

Available on crate feature armour only.

type Key = K

type Tx<'a> = VarTypedMapTx<'a, K, T, C, H> where Self: 'a

The typed handle handed to the closure. Owns this collection’s locked-shard guards plus one collection-wide event log. Each family is a distinct type holding its own guard combination (durability+seize / durability+index / engine+seize / engine+index / type-erased var ptr).

fn shard_for_key(&self, key: &K) -> usize

Route a key to its shard (xxh3(key) % shard_count, honoring shard_prefix_bits).

fn begin_tx(&self) -> VarTypedMapTx<'_, K, T, C, H>

Create an empty transaction handle: no shards locked yet, empty event log, epoch guard entered (for families that need one).

fn lock_shard_into<'a>( &'a self, shard_id: usize, tx: &mut VarTypedMapTx<'a, K, T, C, H>, )

Lock one shard and append its guard(s) into tx. Called by the scheduler in global canonical order.

fn release_locks(&self, tx: &mut VarTypedMapTx<'_, K, T, C, H>) -> SyncNeeds

Phase 1: collect shards needing sync (read should_sync before dropping), then release all of this collection’s shard locks. The event log stays.

fn run_sync(&self, needs: SyncNeeds) -> DbResult<()>

Phase 2: re-lock and sync() the reported shards. No-op when empty.

fn replay_hooks(&self, tx: VarTypedMapTx<'_, K, T, C, H>)

Phase 3: replay the collection-wide event log via the write hook, in closure order. Called only after EVERY collection has done phase 1.

fn collection_id(&self) -> usize

impl<K: Key + Send + Sync + Hash + Eq, T: Send + Sync, C: Codec<T> + Clone, H: TypedWriteHook<K, T>> ReplicationTarget for VarTypedMap<K, T, C, H>

Available on crate feature replication only.

fn apply_entry( &self, shard_inner: &mut ShardInner, shard_id: u8, file_id: u32, entry_offset: u64, header: &EntryHeader, key: &[u8], value: &[u8], ) -> DbResult<ApplyOutcome>

Apply entry with known key/value split (streaming mode, O(1) routing). Returns the outcome so the registry can account dead bytes.

fn try_apply_entry( &self, shard_inner: &mut ShardInner, shard_id: u8, file_id: u32, entry_offset: u64, header: &EntryHeader, raw_after_header: &[u8], ) -> DbResult<ApplyOutcome>

Try to apply entry with CRC matching (catch-up mode). Returns ApplyOutcome::NotMatched if CRC fails (key belongs to a different target).

fn key_len(&self) -> usize

The key length (K) for this tree type.

impl<T, C, H> SchemaCollection for VarTypedMap<T::SelfId, T, C, H>

where T: CollectionMeta + GetRefs + Send + Sync + 'static, T::SelfId: Key + GetRefs + GetType + Hash + Eq + Send + Sync + 'static, C: Codec<T> + Clone + Send + Sync + 'static, H: TypedWriteHook<T::SelfId, T> + 'static,

Available on crate feature var-collections only.

const STORAGE: StorageClass

Physical storage class of this collection.

type K = <T as CollectionMeta>::SelfId

type V = T

fn scan(&self, f: &mut dyn FnMut(&Self::K, &Self::V))

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

fn with_value(&self, key: &Self::K, f: &mut dyn FnMut(&Self::V)) -> bool

false — no record; true — record exists and f was called with the value.