Struct Evicted

pub struct Evicted<'a, K, V> { /* private fields */ }

A value which was evicted from a map.

Due to the nature of concurrent data structures, memory often cannot be reclaimed the instant a writer decides it no longer needs to be used. This goes for flashmap as well. When a value is removed from the map, an Evicted<'a, V> is returned. This type only guarantees that the value is valid for reads for the duration of 'a, which will never outlive the guard which is protecting the value. To use the evicted value after the associated guard is dropped, it must be leaked, at which point the programmer is responsible for dropping or claiming ownership of the value. If an evicted value is not leaked, then it will be dropped at some unspecified point after (or while) the guard is dropped when it is safe to do so.

Inspecting an evicted value

Evicted implements Deref, so you can get immutable access to the underlying value.

use flashmap::{self, Evicted};

let (mut write, read) = flashmap::new::<u32, u32>();
let mut guard = write.guard();

// Insert a key-value pair
guard.insert(0, 0);

// Evict the entry and its value
let removed: Evicted<'_, u32, u32> = guard.remove(0).unwrap();

// Inspect the evicted value by dereferencing it
assert_eq!(*removed, 0);

Leaking

To use an evicted value beyond the lifetime of the guard which provides it, you must leak the value. This also means that you’re responsible for manually dropping it. See leak and Leaked for more information.

Implementations

impl<'a, K, V> Evicted<'a, K, V>

pub fn leak(evicted: Self) -> Leaked<V>

Leaks the contained value, extending its lifetime until it is manually converted into an owned value or dropped.

The primary means for safely turning a leaked value into an owned value are through the reclaim_one and reclaimer methods. For dropping a leaked value, you can use the drop_lazily method. For more advanced use, see the Leaked type and its associated into_inner method.

Examples

use flashmap::{self, Evicted, Leaked};

let (mut write, read) = flashmap::new::<u32, String>();
let mut guard = write.guard();

// Insert a couple values
guard.insert(1, "a".to_owned());
guard.insert(2, "b".to_owned());

// Evict those values
let a = guard.remove(1).map(Evicted::leak).unwrap();
let b = guard.remove(2).map(Evicted::leak).unwrap();

guard.publish();

// Reclaim one
let a = write.reclaim_one(a);
assert_eq!(a, "a");

// Lazily drop another
write.guard().drop_lazily(b);

Trait Implementations

impl<K, V> Deref for Evicted<'_, K, V>

type Target = V

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.