Struct compressible_map::CompressibleMap

pub struct CompressibleMap<K, V, A, H = RandomState> where
    A: Compression<Data = V>,  { /* fields omitted */ }

A hash map that allows compressing the least recently used values. Useful when you need to store a lot of large values in memory. You must define your own compression method for the value type using the Compressible and Decompressible traits.

Call the compress_lru method to compress the least recently used value. The most recently used values will stay uncompressed in a cache.

Any mutable access (&mut self) that misses the cache will decompress and cache the value inline. You can call get to prefetch into the cache and avoid extra latency on further accesses.

Any immutable access (&self, e.g. from multiple threads), like get_const, cannot update the cache. Instead, it will record accesses and store decompressed values in a LocalCache that can be used later to update the cache with flush_local_cache.

Implementations

impl<K, V, H, A> CompressibleMap<K, V, A, H> where
    K: Clone + Eq + Hash,
    H: BuildHasher + Default,
    A: Compression<Data = V>, 

pub fn new(compression_params: A) -> Self

pub fn compression_params(&self) -> &A

pub fn from_all_compressed(
    compression_params: A,
    compressed: HashMap<K, Compressed<A>, H>
) -> Self

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

Insert a new value and drop the old one.

pub fn insert_compressed(
    &mut self,
    key: K,
    value: Compressed<A>
) -> Option<MaybeCompressed<V, Compressed<A>>>

Insert a compressed value, returning any pre-existing entry.

pub fn replace(&mut self, key: K, value: V) -> Option<V>

Insert a new value and return the old one if it exists, which requires decompressing it.

pub fn compress_lru(&mut self)

pub fn remove_lru(&mut self) -> Option<(K, V)>

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

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

pub fn get_or_insert_with(
    &mut self,
    key: K,
    on_missing: impl FnOnce() -> V
) -> &mut V

pub fn get_const<'a>(
    &'a self,
    key: K,
    local_cache: &'a LocalCache<K, V, H>
) -> Option<&'a V>

Used for thread-safe access or to borrow multiple values at once. The cache will not be updated, but accesses will be recorded in the provided LocalCache. The interior mutability of the local cache has a cost (more heap indirection), but it allows us to borrow multiple values at once. Call flush_local_cache to update the "global" cache with the local cache.

pub fn get_copy_without_caching(&self, key: &K) -> Option<V> where
    V: Clone, 

Returns a copy of the value at key, which may involve decompression. WARNING: the cache will not be updated. This is useful for read-modify-write scenarios where you would just insert the modified value back into the map, which defeats the purpose of caching it on read.

pub fn flush_local_cache(&mut self, local_cache: LocalCache<K, V, H>)

Updates the cache and it's approximate LRU order after calling get_const some number of times. WARNING/TODO: There is currently no mechanism to prevent overwriting newer compressed data with old data from a local cache.

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

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

Removes the value and returns it if it exists, decompressing it first.

pub fn clear(&mut self)

pub fn len(&self) -> usize

pub fn len_cached(&self) -> usize

pub fn len_compressed(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn keys<'a>(&'a self) -> impl Iterator<Item = &K> where
    Compressed<A>: 'a, 

pub fn iter_maybe_compressed<'a>(
    &'a self
) -> impl Iterator<Item = (&K, MaybeCompressed<&V, &Compressed<A>>)> where
    Compressed<A>: 'a, 

Iterate over all (key, value) pairs, but compressed values will not be decompressed inline. Does not affect the cache.

pub fn into_iter(
    self
) -> impl Iterator<Item = (K, MaybeCompressed<V, Compressed<A>>)>