Struct View

pub struct View<G> { /* private fields */ }

Wraps a guard and provides a view into the map based on that guard.

This type is the proxy through which all read and write operations are performed on the map.

Implementations

impl<K, V, S, G> View<G>

where G: ReadAccess<Map = HashMap<Alias<K>, Alias<V>, S>>, S: BuildHasher,

pub fn is_empty(&self) -> bool

Returns whether or not the underlying map is empty.

Examples

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

// The map is empty
assert!(read.guard().is_empty());

// Add something to the map
write.guard().insert(10, 20);

// The map is no longer empty
assert!(!read.guard().is_empty());

pub fn len(&self) -> usize

Returns the length of the map.

Note that this just returns the length of the snapshot this guard is viewing. This value should not be relied upon for program correctness.

Examples

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

// There are no entries in the map currently
assert_eq!(read.guard().len(), 0);

// Add two entires
let mut write_guard = write.guard();
write_guard.insert(1, 42);
write_guard.insert(2, 43);
write_guard.publish();

// Now new read guards will see those entries
assert_eq!(read.guard().len(), 2);

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

where K: Borrow<Q> + Eq + Hash, Q: Hash + Eq + ?Sized,

Returns whether or not the map contains the given key.

Examples

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

write.guard().insert(0, 0);

let guard = read.guard();
assert!(guard.contains_key(&0));
assert!(!guard.contains_key(&1));

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

where K: Borrow<Q> + Eq + Hash, Q: Hash + Eq + ?Sized,

Returns a reference to the value corresponding to the key.

Examples

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

write.guard().insert("apples".to_owned(), "oranges".to_owned());

let guard = read.guard();
assert_eq!(guard.get("apples").unwrap(), "oranges");
assert!(guard.get("bananas").is_none());

pub fn iter<'read>(&'read self) -> impl Iterator<Item = (&K, &V)> + '_

where (K, V): 'read,

An iterator visiting all key-value pairs in arbitrary order.

Examples

let (mut write, read) = flashmap::new::<i8, i8>();

let mut guard = write.guard();
guard.insert(3, 5);
guard.insert(5, 7);
guard.insert(7, 11);
guard.publish();

let mut result = 0i8;
for (&key, &value) in read.guard().iter() {
    result += key * value;
}

// 3*5 + 5*7 + 7*11 == 127 == i8::MAX
assert_eq!(result, i8::MAX);

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

where (K, V): 'read,

An iterator visiting all keys in arbitrary order.

Examples

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

let mut guard = write.guard();
guard.insert(1, "one".to_owned());
guard.insert(10, "ten".to_owned());
guard.insert(100, "one hundred".to_owned());
guard.publish();

let mut result = 0u32;
for &key in read.guard().keys() {
    result += key;
}

// 1 + 10 + 100 == 111
assert_eq!(result, 111);

pub fn values<'read>(&'read self) -> impl Iterator<Item = &V> + '_

where (K, V): 'read,

An iterator visiting all values in arbitrary order.

Examples

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

let mut guard = write.guard();
guard.insert("one".to_owned(), 1);
guard.insert("ten".to_owned(), 10);
guard.insert("one hundred".to_owned(), 100);
guard.publish();

let mut result = 0u32;
for &key in read.guard().values() {
    result += key;
}

// 1 + 10 + 100 == 111
assert_eq!(result, 111);

impl<'guard, K, V, S> View<WriteGuard<'guard, K, V, S>>

where K: Eq + Hash, S: BuildHasher,

pub fn insert<'ret>(&mut self, key: K, value: V) -> Option<Evicted<'ret, K, V>>

where 'guard: 'ret,

Inserts a key-value pair into the map.

If the map did not have this key present, then None is returned. If it did, then the evicted value is returned. See Evicted for details.

Examples

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

assert!(guard.insert(17, "seven teen".to_owned()).is_none());
assert_eq!(&*guard.insert(17, "seventeen".to_owned()).unwrap(), "seven teen");

pub fn replace<'ret, F>(&mut self, key: K, op: F) -> Option<Evicted<'ret, K, V>>

where F: FnOnce(&V) -> V, 'guard: 'ret,

Replaces the value associated with the given key according to the provided function.

If the key is not present, then the function is not called, and None is returned. If the key is present, then the function is called with the current value provided as the argument, the value in the map is replaced, and the evicted value is returned. See Evicted for details.

Examples

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

guard.insert(1, "a".to_owned());

// The key 0 is not in the map, so nothing changes
assert!(guard.replace(0, |_| String::new()).is_none());
assert_eq!(guard.get(&1).unwrap(), "a");

// The key 1 is in the map, so the closure gets called
let evicted = guard.replace(1, |old| {
    assert_eq!(old, "a");
    "b".to_owned()
}).unwrap();

// We evicted the old value "a"
assert_eq!(&*evicted, "a");

// And now "b" is in the map
assert_eq!(guard.get(&1).unwrap(), "b");

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

where 'guard: 'ret,

Removes a key from the map, returning the value at the key if the key was previously in the map. See Evicted for details on accessing the removed value.

Examples

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

guard.insert(0, "a".to_owned());

assert_eq!(&*guard.remove(0).unwrap(), "a");
assert!(guard.remove(0).is_none());
assert!(guard.remove(1).is_none());

pub fn drop_lazily(&self, leaked: Leaked<V>)

Takes ownership of a leaked value and drops the inner value when it is safe to do so.

There are no guarantees regarding when the leaked value will be dropped. It is only guaranteed that it will eventually be dropped provided that no handles or guards associated with this map are leaked or forgotten.

Panics

Panics if the provided leaked value came from a different map then the one this guard is associated with. Note that it is not required that this method is called with the same guard that created the leaked value.

Examples

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

write.guard().insert("ferris".to_owned(), "crab".to_owned());

// ~~ stuff happens ~~

let mut guard = write.guard();

// Remove the value and leak it
let leaked = guard.remove("ferris".to_owned())
    .map(Evicted::leak)
    .unwrap();
assert_eq!(&*leaked, "crab");

// We decide we don't need to keep the leaked value around, so we tell the guard
// to drop it when it is safe to do so
guard.drop_lazily(leaked);

guard.publish();

pub fn publish(self)

Consumes this view and its guard, publishing all previous changes to the map.

This has the same effect as dropping the view. Note that the changes will only be visible through newly created read or write guards.