Merge pull request #114 from moka-rs/iterator

Add `iter` method to create an iterator to `unsync`, `sync` and `future` caches

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Moka — Change Log
 
+## Version 0.8.2
+
+### Added
+
+- Add iterator to the following caches: ([#114][gh-pull-0114])
+ - `sync::Cache`
+ - `sync::SegmentedCache`
+ - `future::Cache`
+ - `unsync::Cache`
+- Implement `IntoIterator` to the all caches (including experimental `dash::Cache`)
+ ([#114][gh-pull-0114])
+
+
 ## Version 0.8.1
 
 ### Added
@@ -287,6 +300,7 @@ The minimum supported Rust version (MSRV) is now 1.51.0 (2021-03-25).
 [gh-issue-0038]: https://github.com/moka-rs/moka/issues/38/
 [gh-issue-0031]: https://github.com/moka-rs/moka/issues/31/
 
+[gh-pull-0114]: https://github.com/moka-rs/moka/pull/114/
 [gh-pull-0105]: https://github.com/moka-rs/moka/pull/105/
 [gh-pull-0104]: https://github.com/moka-rs/moka/pull/104/
 [gh-pull-0103]: https://github.com/moka-rs/moka/pull/103/

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "moka"
-version = "0.8.1"
+version = "0.8.2"
 edition = "2018"
 rust-version = "1.51"
 

src/cht/map/bucket.rs

@@ -334,6 +334,33 @@ impl<'g, K: 'g + Eq, V: 'g> BucketArray<K, V> {
 
  loop_result.returned().flatten()
  }
+
+ pub(crate) fn keys<F, T>(
+ &self,
+ guard: &'g Guard,
+ with_key: &mut F,
+ ) -> Result<Vec<T>, RelocatedError>
+ where
+ F: FnMut(&K) -> T,
+ {
+ let mut keys = Vec::new();
+
+ for bucket in self.buckets.iter() {
+ let bucket_ptr = bucket.load_consume(guard);
+
+ if is_sentinel(bucket_ptr) {
+ return Err(RelocatedError);
+ }
+
+ if let Some(bucket_ref) = unsafe { bucket_ptr.as_ref() } {
+ if !is_tombstone(bucket_ptr) {
+ keys.push(with_key(&bucket_ref.key));
+ }
+ }
+ }
+
+ Ok(keys)
+ }
 }
 
 impl<'g, K: 'g, V: 'g> BucketArray<K, V> {

src/cht/map/bucket_array_ref.rs

@@ -266,6 +266,34 @@ where
 
  result
  }
+
+ pub(crate) fn keys<F, T>(&self, mut with_key: F) -> Vec<T>
+ where
+ F: FnMut(&K) -> T,
+ {
+ let guard = &crossbeam_epoch::pin();
+ let current_ref = self.get(guard);
+ let mut bucket_array_ref = current_ref;
+
+ let result;
+
+ loop {
+ match bucket_array_ref.keys(guard, &mut with_key) {
+ Ok(keys) => {
+ result = keys;
+ break;
+ }
+ Err(_) => {
+ bucket_array_ref =
+ bucket_array_ref.rehash(guard, self.build_hasher, RehashOp::Expand);
+ }
+ }
+ }
+
+ self.swing(guard, current_ref, bucket_array_ref);
+
+ result
+ }
 }
 
 impl<'a, 'g, K, V, S> BucketArrayRef<'a, K, V, S> {

src/cht/segment.rs

@@ -530,6 +530,28 @@ impl<K: Hash + Eq, V, S: BuildHasher> HashMap<K, V, S> {
  result
  }
 
+ pub(crate) fn keys<F, T>(&self, segment: usize, with_key: F) -> Option<Vec<T>>
+ where
+ F: FnMut(&K) -> T,
+ {
+ if segment >= self.segments.len() {
+ return None;
+ }
+
+ let Segment {
+ ref bucket_array,
+ ref len,
+ } = self.segments[segment];
+
+ let bucket_array_ref = BucketArrayRef {
+ bucket_array,
+ build_hasher: &self.build_hasher,
+ len,
+ };
+
+ Some(bucket_array_ref.keys(with_key))
+ }
+
  #[inline]
  pub(crate) fn hash<Q>(&self, key: &Q) -> u64
  where
@@ -538,6 +560,10 @@ impl<K: Hash + Eq, V, S: BuildHasher> HashMap<K, V, S> {
  {
  bucket::hash(&self.build_hasher, key)
  }
+
+ pub(crate) fn actual_num_segments(&self) -> usize {
+ self.segments.len()
+ }
 }
 
 impl<K, V, S> Drop for HashMap<K, V, S> {
@@ -1610,4 +1636,49 @@ mod tests {
 
  run_deferred();
  }
+
+ #[test]
+ fn keys_in_single_segment() {
+ let map =
+ HashMap::with_num_segments_capacity_and_hasher(1, 0, DefaultHashBuilder::default());
+
+ assert!(map.is_empty());
+ assert_eq!(map.len(), 0);
+
+ const NUM_KEYS: usize = 200;
+
+ for i in 0..NUM_KEYS {
+ let key = Arc::new(i);
+ let hash = map.hash(&key);
+ assert_eq!(map.insert_entry_and(key, hash, i, |_, v| *v), None);
+ }
+
+ assert!(!map.is_empty());
+ assert_eq!(map.len(), NUM_KEYS);
+
+ let mut keys = map.keys(0, |k| Arc::clone(k)).unwrap();
+ assert_eq!(keys.len(), NUM_KEYS);
+ keys.sort_unstable();
+
+ for (i, key) in keys.into_iter().enumerate() {
+ assert_eq!(i, *key);
+ }
+
+ for i in (0..NUM_KEYS).step_by(2) {
+ assert_eq!(map.remove(&i, map.hash(&i)), Some(i));
+ }
+
+ assert!(!map.is_empty());
+ assert_eq!(map.len(), NUM_KEYS / 2);
+
+ let mut keys = map.keys(0, |k| Arc::clone(k)).unwrap();
+ assert_eq!(keys.len(), NUM_KEYS / 2);
+ keys.sort_unstable();
+
+ for (i, key) in keys.into_iter().enumerate() {
+ assert_eq!(i, *key / 2);
+ }
+
+ run_deferred();
+ }
 }

src/dash/cache.rs

@@ -1,6 +1,6 @@
 use super::{
  base_cache::{BaseCache, HouseKeeperArc, MAX_SYNC_REPEATS, WRITE_RETRY_INTERVAL_MICROS},
- CacheBuilder, ConcurrentCacheExt, Iter,
+ CacheBuilder, ConcurrentCacheExt, EntryRef, Iter,
 };
 use crate::{
  sync::{housekeeper::InnerSync, Weigher, WriteOp},
@@ -25,9 +25,6 @@ use std::{
 /// Since `DashMap` employs read-write locks on internal shards, it will have lower
 /// concurrency on retrievals and updates than other caches.
 ///
-/// On the other hand, `dash` cache provides iterator, which returns immutable
-/// references to the entries in a cache. Other caches do not provide iterator.
-///
 /// `dash` cache performs a best-effort bounding of the map using an entry
 /// replacement algorithm to determine which entries to evict when the capacity is
 /// exceeded.
@@ -436,13 +433,24 @@ where
  V: 'a,
  S: BuildHasher + Clone,
 {
- /// Creates an iterator over a `moka::dash::Cache` yielding immutable references.
+ /// Creates an iterator visiting all key-value pairs in arbitrary order. The
+ /// iterator element type is [`EntryRef<'a, K, V, S>`][moka-entry-ref].
+ ///
+ /// Unlike the `get` method, visiting entries via an iterator do not update the
+ /// historic popularity estimator or reset idle timers for keys.
+ ///
+ /// # Guarantees
+ ///
+ /// **TODO**
+ ///
+ /// # Locking behavior
  ///
- /// **Locking behavior**: This iterator relies on the iterator of
- /// [`dashmap::DashMap`][dashmap-iter], which employs read-write locks. May
- /// deadlock if the thread holding an iterator attempts to update the cache.
+ /// This iterator relies on the iterator of [`dashmap::DashMap`][dashmap-iter],
+ /// which employs read-write locks. May deadlock if the thread holding an
+ /// iterator attempts to update the cache.
  ///
- /// [dashmap-iter]: https://docs.rs/dashmap/5.2.0/dashmap/struct.DashMap.html#method.iter
+ /// [moka-entry-ref]: ./struct.EntryRef.html
+ /// [dashmap-iter]: <https://docs.rs/dashmap/*/dashmap/struct.DashMap.html#method.iter>
  ///
  /// # Examples
  ///
@@ -478,6 +486,21 @@ where
  }
 }
 
+impl<'a, K, V, S> IntoIterator for &'a Cache<K, V, S>
+where
+ K: 'a + Eq + Hash,
+ V: 'a,
+ S: BuildHasher + Clone,
+{
+ type Item = EntryRef<'a, K, V, S>;
+
+ type IntoIter = Iter<'a, K, V, S>;
+
+ fn into_iter(self) -> Self::IntoIter {
+ self.iter()
+ }
+}
+
 // private methods
 impl<K, V, S> Cache<K, V, S>
 where
@@ -902,7 +925,7 @@ mod tests {
 
  let mut key_set = std::collections::HashSet::new();
 
- for entry in cache.iter() {
+ for entry in &cache {
  let (key, value) = entry.pair();
  assert_eq!(value, &make_value(*key));
 
@@ -934,7 +957,10 @@ mod tests {
  ///
  #[test]
  fn test_iter_multi_threads() {
+ use std::collections::HashSet;
+
  const NUM_KEYS: usize = 1024;
+ const NUM_THREADS: usize = 16;
 
  fn make_value(key: usize) -> String {
  format!("val: {}", key)
@@ -955,7 +981,7 @@ mod tests {
 
  // https://rust-lang.github.io/rust-clippy/master/index.html#needless_collect
  #[allow(clippy::needless_collect)]
- let handles = (0..16usize)
+ let handles = (0..NUM_THREADS)
  .map(|n| {
  let cache = cache.clone();
  let rw_lock = Arc::clone(&rw_lock);
@@ -974,8 +1000,8 @@ mod tests {
  // This thread will iterate the cache.
  std::thread::spawn(move || {
  let read_lock = rw_lock.read().unwrap();
- let mut key_set = std::collections::HashSet::new();
- for entry in cache.iter() {
+ let mut key_set = HashSet::new();
+ for entry in &cache {
  let (key, value) = entry.pair();
  assert_eq!(value, &make_value(*key));
  key_set.insert(*key);
@@ -992,6 +1018,10 @@ mod tests {
  std::mem::drop(write_lock);
 
  handles.into_iter().for_each(|h| h.join().expect("Failed"));
+
+ // Ensure there are no missing or duplicate keys in the iteration.
+ let key_set = cache.iter().map(|ent| *ent.key()).collect::<HashSet<_>>();
+ assert_eq!(key_set.len(), NUM_KEYS);
  }
 
  #[test]