[−][src]Struct evmap::WriteHandle
A handle that may be used to modify the eventually consistent map.
Note that any changes made to the map will not be made visible to readers until refresh()
is
called.
Examples
let x = ('x', 42); let (r, mut w) = evmap::new(); // the map is uninitialized, so all lookups should return None assert_eq!(r.get_and(&x.0, |rs| rs.len()), None); w.refresh(); // after the first refresh, it is empty, but ready assert_eq!(r.get_and(&x.0, |rs| rs.len()), None); w.insert(x.0, x); // it is empty even after an add (we haven't refresh yet) assert_eq!(r.get_and(&x.0, |rs| rs.len()), None); w.refresh(); // but after the swap, the record is there! assert_eq!(r.get_and(&x.0, |rs| rs.len()), Some(1)); assert_eq!(r.get_and(&x.0, |rs| rs.iter().any(|v| v.0 == x.0 && v.1 == x.1)), Some(true));
Methods
impl<K, V, M, S> WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
pub fn refresh(&mut self) -> &mut Self
[src]
Refresh the handle used by readers so that pending writes are made visible.
This method needs to wait for all readers to move to the new handle so that it can replay the operational log onto the stale map copy the readers used to use. This can take some time, especially if readers are executing slow operations, or if there are many of them.
pub fn destroy(self)
[src]
Drop this map without preserving one side for reads.
Normally, the maps are not deallocated until all readers have also gone away.
When this method is called, the map is immediately (but safely) taken away from all
readers, causing all future lookups to return None
.
use std::thread; let (r, mut w) = evmap::new(); // start some readers let readers: Vec<_> = (0..4).map(|_| { let r = r.clone(); thread::spawn(move || { loop { let l = r.len(); if l == 0 { if r.is_destroyed() { // the writer destroyed the map! break; } thread::yield_now(); } else { // the reader will either see all the reviews, // or none of them, since refresh() is atomic. assert_eq!(l, 4); } } }) }).collect(); // do some writes w.insert(0, String::from("foo")) .insert(1, String::from("bar")) .insert(2, String::from("baz")) .insert(3, String::from("qux")); // expose the writes w.refresh(); assert_eq!(r.len(), 4); // refresh a few times to exercise the readers for _ in 0..10 { w.refresh(); } // now blow the map away w.destroy(); // all the threads should eventually see that the map was destroyed for r in readers.into_iter() { assert!(r.join().is_ok()); }
pub fn pending(&self) -> &[Operation<K, V>]
[src]
Gives the sequence of operations that have not yet been applied.
Note that until the first call to refresh
, the sequence of operations is always empty.
let x = ('x', 42); let (r, mut w) = evmap::new(); // before the first refresh, no oplog is kept w.refresh(); assert_eq!(w.pending(), &[]); w.insert(x.0, x); assert_eq!(w.pending(), &[Operation::Add(x.0, x)]); w.refresh(); w.remove(x.0, x); assert_eq!(w.pending(), &[Operation::Remove(x.0, x)]); w.refresh(); assert_eq!(w.pending(), &[]);
pub fn flush(&mut self) -> &mut Self
[src]
Refresh as necessary to ensure that all operations are visible to readers.
WriteHandle::refresh
will always wait for old readers to depart and swap the maps.
This method will only do so if there are pending operations.
pub fn set_meta(&mut self, meta: M) -> M
[src]
Set the metadata.
Will only be visible to readers after the next call to refresh()
.
pub fn insert(&mut self, k: K, v: V) -> &mut Self
[src]
Add the given value to the value-set of the given key.
The updated value-set will only be visible to readers after the next call to refresh()
.
pub fn update(&mut self, k: K, v: V) -> &mut Self
[src]
Replace the value-set of the given key with the given value.
With the smallvec
feature enabled, replacing the value will automatically
deallocate any heap storage and place the new value back into
the SmallVec
inline storage. This can improve cache locality for common
cases where the value-set is only ever a single element.
See the doc section on this for more information.
The new value will only be visible to readers after the next call to refresh()
.
pub fn clear(&mut self, k: K) -> &mut Self
[src]
Clear the value-set of the given key, without removing it.
If a value-set already exists, this will clear it but leave the allocated memory intact for reuse, or if no associated value-set exists an empty value-set will be created for the given key.
The new value will only be visible to readers after the next call to refresh()
.
pub fn remove(&mut self, k: K, v: V) -> &mut Self
[src]
Remove the given value from the value-set of the given key.
The updated value-set will only be visible to readers after the next call to refresh()
.
pub fn empty(&mut self, k: K) -> &mut Self
[src]
Remove the value-set for the given key.
The value-set will only disappear from readers after the next call to refresh()
.
pub fn purge(&mut self) -> &mut Self
[src]
Purge all value-sets from the map.
The map will only appear empty to readers after the next call to refresh()
.
Note that this will iterate once over all the keys internally.
pub fn retain<F>(&mut self, k: K, f: F) -> &mut Self where
F: Fn(&V) -> bool + 'static + Send + Sync,
[src]
F: Fn(&V) -> bool + 'static + Send + Sync,
Retain elements for the given key using the provided predicate function.
The remaining value-set will only be visible to readers after the next call to refresh()
pub fn fit(&mut self, k: K) -> &mut Self
[src]
Shrinks a value-set to it's minimum necessary size, freeing memory
and potentially improving cache locality by switching to inline storage
if the smallvec
feature is used.
The optimized value-set will only be visible to readers after the next call to refresh()
pub fn fit_all(&mut self) -> &mut Self
[src]
Like WriteHandle::fit
, but shrinks all value-sets in the map.
The optimized value-sets will only be visible to readers after the next call to refresh()
pub fn reserve(&mut self, k: K, additional: usize) -> &mut Self
[src]
Reserves capacity for some number of additional elements in a value-set, or creates an empty value-set for this key with the given capacity if it doesn't already exist.
Readers are unaffected by this operation, but it can improve performance by pre-allocating space for large value-sets.
Methods from Deref<Target = ReadHandle<K, V, M, S>>
pub fn len(&self) -> usize
[src]
Returns the number of non-empty keys present in the map.
pub fn is_empty(&self) -> bool
[src]
Returns true if the map contains no elements.
pub fn meta(&self) -> Option<M>
[src]
Get the current meta value.
pub fn get_and<Q: ?Sized, F, T>(&self, key: &Q, then: F) -> Option<T> where
F: FnOnce(&[V]) -> T,
K: Borrow<Q>,
Q: Hash + Eq,
[src]
F: FnOnce(&[V]) -> T,
K: Borrow<Q>,
Q: Hash + Eq,
Applies a function to the values corresponding to the key, and returns the result.
The key may be any borrowed form of the map's key type, but Hash
and Eq
on the borrowed
form must match those for the key type.
Note that not all writes will be included with this read -- only those that have been
refreshed by the writer. If no refresh has happened, this function returns None
.
If no values exist for the given key, no refresh has happened, or the map has been
destroyed, then
will not be called, and None
will be returned.
pub fn meta_get_and<Q: ?Sized, F, T>(
&self,
key: &Q,
then: F
) -> Option<(Option<T>, M)> where
F: FnOnce(&[V]) -> T,
K: Borrow<Q>,
Q: Hash + Eq,
[src]
&self,
key: &Q,
then: F
) -> Option<(Option<T>, M)> where
F: FnOnce(&[V]) -> T,
K: Borrow<Q>,
Q: Hash + Eq,
Applies a function to the values corresponding to the key, and returns the result alongside the meta information.
The key may be any borrowed form of the map's key type, but Hash
and Eq
on the borrowed
form must match those for the key type.
Note that not all writes will be included with this read -- only those that have been
refreshed by the writer. If no refresh has happened, or if the map has been closed by the
writer, this function returns None
.
If no values exist for the given key, then
will not be called, and Some(None, _)
is
returned.
pub fn is_destroyed(&self) -> bool
[src]
If the writer has destroyed this map, this method will return true.
See WriteHandle::destroy
.
pub fn contains_key<Q: ?Sized>(&self, key: &Q) -> bool where
K: Borrow<Q>,
Q: Hash + Eq,
[src]
K: Borrow<Q>,
Q: Hash + Eq,
Returns true if the map contains any values for the specified key.
The key may be any borrowed form of the map's key type, but Hash
and Eq
on the borrowed
form must match those for the key type.
pub fn for_each<F>(&self, f: F) where
F: FnMut(&K, &[V]),
[src]
F: FnMut(&K, &[V]),
Read all values in the map, and transform them into a new collection.
Be careful with this function! While the iteration is ongoing, any writer that tries to refresh will block waiting on this reader to finish.
pub fn map_into<Map, Collector, Target>(&self, f: Map) -> Collector where
Map: FnMut(&K, &[V]) -> Target,
Collector: FromIterator<Target>,
[src]
Map: FnMut(&K, &[V]) -> Target,
Collector: FromIterator<Target>,
Read all values in the map, and transform them into a new collection.
Trait Implementations
impl<K, V, M, S> Extend<(K, V)> for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
fn extend<I: IntoIterator<Item = (K, V)>>(&mut self, iter: I)
[src]
impl<K, V, M, S> Drop for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
impl<K, V, M, S> Deref for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + ShallowCopy,
M: 'static + Clone,
type Target = ReadHandle<K, V, M, S>
The resulting type after dereferencing.
fn deref(&self) -> &Self::Target
[src]
Auto Trait Implementations
impl<K, V, M, S> Send for WriteHandle<K, V, M, S> where
K: Send,
M: Send,
S: Send,
V: Send,
K: Send,
M: Send,
S: Send,
V: Send,
impl<K, V, M = (), S = RandomState> !Sync for WriteHandle<K, V, M, S>
Blanket Implementations
impl<T, U> Into for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From for T
[src]
impl<T, U> TryFrom for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T> Borrow for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T, U> TryInto for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,