pub struct SharedHashMap<K: Copy + Eq + 'static, V: Copy + 'static> { /* private fields */ }Implementations§
Sourcepub fn create(path: impl AsRef<Path>, capacity: usize) -> Result<Self, MapError>
pub fn create(path: impl AsRef<Path>, capacity: usize) -> Result<Self, MapError>
Obtain the map at path, initializing an empty one if the path does
not yet exist and attaching to it if it does. Attaching leaves live
entries in place; a region built with a different capacity or
payload type is a LayoutMismatch. reset
reinitializes.
Sourcepub fn reset(path: impl AsRef<Path>, capacity: usize) -> Result<Self, MapError>
pub fn reset(path: impl AsRef<Path>, capacity: usize) -> Result<Self, MapError>
Truncate the map at path and initialize a fresh empty one,
discarding whatever entries a live peer holds. For a caller that
knows it owns the path.
pub fn open( path: impl AsRef<Path>, expected_capacity: usize, ) -> Result<Self, MapError>
pub fn capacity(&self) -> usize
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
Sourcepub fn insert(&self, key: K, value: V) -> Result<InsertOutcome, MapError>
pub fn insert(&self, key: K, value: V) -> Result<InsertOutcome, MapError>
Insert or update. Returns Inserted for a new key,
Updated when an existing key’s value was overwritten,
Err(Full) if the table has no slot for the key (probed
every slot without finding Empty, a key match, or a
reclaimable tombstone).
§Tombstone reuse
Insert tracks the FIRST tombstone seen during the probe.
If the probe terminates at an Empty (key absent) AND a
tombstone was seen, the tombstone slot is reclaimed instead
of consuming the Empty. This eliminates the need for an
explicit compact() call in steady-state insert/remove
workloads. compact() is still useful for bulk reclamation
in workloads that don’t naturally trigger reuse (e.g. a
long insert-only period after heavy removes).
Sourcepub fn contains_key(&self, key: &K) -> bool
pub fn contains_key(&self, key: &K) -> bool
True if key is present.
Sourcepub fn clear(&self)
pub fn clear(&self)
Clear the entire map. Marks every slot Empty and resets both the live count and the tombstone counter to 0. Not concurrency-safe vs concurrent insert/remove - callers should ensure no other writers are active when calling this.
Sourcepub fn tombstone_count(&self) -> usize
pub fn tombstone_count(&self) -> usize
Current tombstone count (slots marked dead by remove that
have not yet been reclaimed by compact).
Sourcepub fn should_compact(&self, threshold_fraction: f64) -> bool
pub fn should_compact(&self, threshold_fraction: f64) -> bool
Heuristic: returns true if tombstones occupy at least
threshold_fraction of capacity. Callers typically pass
0.30 (30 %) - past that, linear-probe chains stretch out
and lookup/insert latency degrades sharply. Cheap O(1).
Sourcepub fn compact(&self) -> Result<usize, MapError>
pub fn compact(&self) -> Result<usize, MapError>
Reclaim tombstones via in-place rebuild. Returns the number of slots reclaimed.
§What it does
Snapshots every Occupied slot into a Vec<(K, V)>, resets
every slot to Empty (zeroing both counters), then re-inserts
each snapshotted pair via the normal probe. Since no
tombstones remain, every key lands as close to its ideal
slot as the live keys permit - probe chains shrink back to
the no-deletion baseline.
§Concurrency
NOT concurrency-safe with insert / remove. The caller
MUST guarantee no other writer (in any process holding an
MMF handle to the same file) is mutating the map during
compact. Readers calling get will see a transient empty
state mid-rebuild and may return spurious None for keys
that are about to be re-inserted; if that is unacceptable,
serialise readers too.
§Cost
O(capacity) for the snapshot + reset, O(live_count *
avg_probe) for re-insert. Allocates a temporary Vec<(K, V)>
sized to the live count. For a 1 M-slot map at 50 % load,
expect ~tens of milliseconds.
Sourcepub fn snapshot(&self) -> Vec<(K, V)>
pub fn snapshot(&self) -> Vec<(K, V)>
Walk and collect all (K, V) pairs currently present. Best- effort snapshot under concurrent writers.
Sourcepub fn load_factor(&self) -> f64
pub fn load_factor(&self) -> f64
Current load factor (count / capacity).
pub fn flush(&self) -> Result<(), MapError>
Sourcepub fn flush_async(&self) -> Result<(), MapError>
pub fn flush_async(&self) -> Result<(), MapError>
Non-blocking flush: schedules a writeback via the OS. Note: Windows is only partially async (sync to page cache, not to disk).