[−][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.
When the WriteHandle
is dropped, the map is immediately (but safely) taken away from all
readers, causing all future lookups to return None
.
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(&x.0).map(|rs| rs.len()), None); w.refresh(); // after the first refresh, it is empty, but ready assert_eq!(r.get(&x.0).map(|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(&x.0).map(|rs| rs.len()), None); w.refresh(); // but after the swap, the record is there! assert_eq!(r.get(&x.0).map(|rs| rs.len()), Some(1)); assert_eq!(r.get(&x.0).map(|rs| rs.iter().any(|v| v.0 == x.0 && v.1 == x.1)), Some(true));
Implementations
impl<K, V, M, S> WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + 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 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-bag of the given key.
The updated value-bag 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-bag of the given key with the given value.
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-bag 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-bag of the given key, without removing it.
If a value-bag already exists, this will clear it but leave the allocated memory intact for reuse, or if no associated value-bag exists an empty value-bag 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-bag of the given key.
The updated value-bag 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-bag for the given key.
The value-bag will only disappear from readers after the next call to refresh()
.
pub fn purge(&mut self) -> &mut Self
[src]
Purge all value-bags 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 unsafe fn retain<F>(&mut self, k: K, f: F) -> &mut Self where
F: FnMut(&V, bool) -> bool + 'static + Send,
[src]
F: FnMut(&V, bool) -> bool + 'static + Send,
Retain elements for the given key using the provided predicate function.
The remaining value-bag will only be visible to readers after the next call to refresh()
Safety
The given closure is called twice for each element, once when called, and once
on swap. It must retain the same elements each time, otherwise a value may exist in one
map, but not the other, leaving the two maps permanently out-of-sync. This is really bad,
as values are aliased between the maps, and are assumed safe to free when they leave the
map during a refresh
. Returning true
when retain
is first called for a value, and
false
the second time would free the value, but leave an aliased pointer to it in the
other side of the map.
The arguments to the predicate function are the current value in the value-bag, and true
if this is the first value in the value-bag on the second map, or false
otherwise. Use
the second argument to know when to reset any closure-local state to ensure deterministic
operation.
So, stated plainly, the given closure must return the same order of true/false for each of the two iterations over the value-bag. That is, the sequence of returned booleans before the second argument is true must be exactly equal to the sequence of returned booleans at and beyond when the second argument is true.
pub fn fit(&mut self, k: K) -> &mut Self
[src]
Shrinks a value-bag to it's minimum necessary size, freeing memory and potentially improving cache locality by switching to inline storage.
The optimized value-bag 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-bags in the map.
The optimized value-bags 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-bag, or creates an empty value-bag 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-bags.
Methods from Deref<Target = ReadHandle<K, V, M, S>>
pub fn factory(&self) -> ReadHandleFactory<K, V, M, S>
[src]
Create a new Sync
type that can produce additional ReadHandle
s for use in other
threads.
pub fn read(&self) -> Option<MapReadRef<K, V, M, S>>
[src]
Take out a guarded live reference to the read side of the map.
This lets you perform more complex read operations on the map.
While the reference lives, the map cannot be refreshed.
If no refresh has happened, or the map has been destroyed, this function returns None
.
See MapReadRef
.
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<ReadGuard<M>>
[src]
Get the current meta value.
pub fn get<'rh, Q: ?Sized>(
&'rh self,
key: &Q
) -> Option<ReadGuard<'rh, Values<V, S>>> where
K: Borrow<Q>,
Q: Hash + Eq,
[src]
&'rh self,
key: &Q
) -> Option<ReadGuard<'rh, Values<V, S>>> where
K: Borrow<Q>,
Q: Hash + Eq,
Returns a guarded reference to the values corresponding to the key.
While the guard lives, the map cannot be refreshed.
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 the map has been destroyed, this
function returns None
.
pub fn get_one<'rh, Q: ?Sized>(&'rh self, key: &Q) -> Option<ReadGuard<'rh, V>> where
K: Borrow<Q>,
Q: Hash + Eq,
[src]
K: Borrow<Q>,
Q: Hash + Eq,
Returns a guarded reference to one value corresponding to the key.
This is mostly intended for use when you are working with no more than one value per key. If there are multiple values stored for this key, there are no guarantees to which element is returned.
While the guard lives, the map cannot be refreshed.
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 the map has been destroyed, this
function returns None
.
pub fn meta_get<Q: ?Sized>(
&self,
key: &Q
) -> Option<(Option<ReadGuard<Values<V, S>>>, M)> where
K: Borrow<Q>,
Q: Hash + Eq,
[src]
&self,
key: &Q
) -> Option<(Option<ReadGuard<Values<V, S>>>, M)> where
K: Borrow<Q>,
Q: Hash + Eq,
Returns a guarded reference to the values corresponding to the key along with the map meta.
While the guard lives, the map cannot be refreshed.
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 the map has been destroyed, this
function returns None
.
If no values exist for the given key, Some(None, _)
is returned.
pub fn is_destroyed(&self) -> bool
[src]
Returns true if the writer has destroyed this map.
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 contains_value<Q: ?Sized, W: ?Sized>(&self, key: &Q, value: &W) -> bool where
K: Borrow<Q>,
V: Borrow<W>,
Q: Hash + Eq,
W: Hash + Eq,
[src]
K: Borrow<Q>,
V: Borrow<W>,
Q: Hash + Eq,
W: Hash + Eq,
Returns true if the map contains the specified value for the specified key.
The key and value may be any borrowed form of the map's respective types, but Hash
and
Eq
on the borrowed form must match.
pub fn map_into<Map, Collector, Target>(&self, f: Map) -> Collector where
Map: FnMut(&K, &Values<V, S>) -> Target,
Collector: FromIterator<Target>,
[src]
Map: FnMut(&K, &Values<V, S>) -> Target,
Collector: FromIterator<Target>,
Read all values in the map, and transform them into a new collection.
Trait Implementations
impl<K, V, M, S> Debug for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone + Debug,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy + Debug,
M: 'static + Clone + Debug,
[src]
K: Eq + Hash + Clone + Debug,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy + Debug,
M: 'static + Clone + Debug,
impl<K, V, M, S> Deref for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
type Target = ReadHandle<K, V, M, S>
The resulting type after dereferencing.
fn deref(&self) -> &Self::Target
[src]
impl<K, V, M, S> Drop for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
impl<K, V, M, S> Extend<(K, V)> for WriteHandle<K, V, M, S> where
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
[src]
K: Eq + Hash + Clone,
S: BuildHasher + Clone,
V: Eq + Hash + ShallowCopy,
M: 'static + Clone,
fn extend<I: IntoIterator<Item = (K, V)>>(&mut self, iter: I)
[src]
Auto Trait Implementations
impl<K, V, M = (), S = RandomState> !RefUnwindSafe for WriteHandle<K, V, M, S>
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>
impl<K, V, M, S> Unpin for WriteHandle<K, V, M, S> where
K: Unpin,
M: Unpin,
V: Unpin,
K: Unpin,
M: Unpin,
V: Unpin,
impl<K, V, M = (), S = RandomState> !UnwindSafe for WriteHandle<K, V, M, S>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> 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, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,