chore(*): update doc

.config/glossary.txt

@@ -1,4 +1,4 @@
-62
+63
 |_key
 50%
 avx2
@@ -60,4 +60,5 @@ vectorized
 VM
 Workflow
 workflow
+x86_64
 Xeon

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Version 2
 
+2.2.2
+
+* Update internal doc.
+
 2.2.1
 
 * Fix a minor Miri specific assertion failure.

Cargo.toml

@@ -2,7 +2,7 @@
 name = "scc"
 description = "High performance containers and utilities for concurrent and asynchronous programming"
 documentation = "https://docs.rs/scc"
-version = "2.2.1"
+version = "2.2.2"
 authors = ["wvwwvwwv <[email protected]>"]
 edition = "2021"
 rust-version = "1.65.0"

README.md

@@ -12,9 +12,7 @@ A collection of high performance containers and utilities for concurrent and asy
 - [`Equivalent`](https://github.com/indexmap-rs/equivalent), [`Loom`](https://github.com/tokio-rs/loom) and [`Serde`](https://github.com/serde-rs/serde) support: `features = ["equivalent", "loom", "serde"]`.
 - Near-linear scalability.
 - No spin-locks and no busy loops.
-- SIMD lookup to scan multiple entries in parallel [^note].
-
-[^note]: Advanced SIMD instructions are used only when respective target features are enabled, e.g., `-C target_feature=+avx2`.
+- SIMD lookup to scan multiple entries in parallel: require `RUSTFLAGS='-C target_feature=+avx2'` on `x86_64`.
 
 #### Concurrent and Asynchronous Containers
 
@@ -80,11 +78,9 @@ assert_eq!(hashmap.read(&3, |_, v| *v), Some(7));
 
 hashmap.entry(4).and_modify(|v| { *v += 1 }).or_insert(5);
 assert_eq!(hashmap.read(&4, |_, v| *v), Some(5));
-
-let future_entry = hashmap.entry_async(3);
 ```
 
-[`HashMap`](#hashmap) does not provide an [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) since it is impossible to confine the lifetime of [`Iterator::Item`](https://doc.rust-lang.org/std/iter/trait.Iterator.html#associatedtype.Item) to the [Iterator](https://doc.rust-lang.org/std/iter/trait.Iterator.html). The limitation can be circumvented by relying on interior mutability, e.g., let the returned reference hold a lock, however it will easily lead to a deadlock if not correctly used, and frequent acquisition of locks may impact performance. Therefore, [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) is not implemented, instead, [`HashMap`](#hashmap) provides a number of methods to iterate over entries synchronously or asynchronously: `any`, `any_async`, `prune`, `prune_async`, `retain`, `retain_async`, `scan`, `scan_async`, `OccupiedEntry::next`, and `OccupiedEntry::next_async`.
+[`HashMap`](#hashmap) does not provide an [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) since it is impossible to confine the lifetime of [`Iterator::Item`](https://doc.rust-lang.org/std/iter/trait.Iterator.html#associatedtype.Item) to the [Iterator](https://doc.rust-lang.org/std/iter/trait.Iterator.html). The limitation can be circumvented by relying on interior mutability, e.g., let the returned reference hold a lock, however it will easily lead to a deadlock if not correctly used, and frequent acquisition of locks may impact performance. Therefore, [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) is not implemented, instead, [`HashMap`](#hashmap) provides a number of methods to iterate over entries synchronously or asynchronously: `any`, `any_async`, `first_entry`, `first_entry_async`, `prune`, `prune_async`, `retain`, `retain_async`, `scan`, `scan_async`, `OccupiedEntry::next`, and `OccupiedEntry::next_async`.
 
 ```rust
 use scc::HashMap;
@@ -110,12 +106,29 @@ hashmap.retain(|k, v| *k == 1 && *v == 2);
 
 // `hash_map::OccupiedEntry` also can return the next closest occupied entry.
 let first_entry = hashmap.first_entry();
-assert!(first_entry.is_some());
+assert_eq!(*first_entry.as_ref().unwrap().key(), 1);
 let second_entry = first_entry.and_then(|e| e.next());
 assert!(second_entry.is_none());
 
+fn is_send<T: Send>(f: &T) -> bool {
+    true
+}
+
 // Asynchronous iteration over entries using `scan_async`.
 let future_scan = hashmap.scan_async(|k, v| println!("{k} {v}"));
+assert!(is_send(&future_scan));
+
+// Asynchronous iteration over entries using the `Entry` API.
+let future_iter = async {
+    let mut iter = hashmap.first_entry_async().await;
+    while let Some(entry) = iter {
+        // `OccupiedEntry` can be sent across awaits and threads.
+        assert!(is_send(&entry));
+        assert_eq!(*entry.key(), 1);
+        iter = entry.next_async().await;
+    }
+};
+assert!(is_send(&future_iter));
 ```
 
 ## `HashSet`
@@ -422,6 +435,5 @@ The expected tail latency of a distribution of latencies of 1048576 insertion op
 
 - [Results on Apple M2 Max (12 cores)](https://github.com/wvwwvwwv/conc-map-bench).
 - [Results on Intel Xeon (32 cores, avx2)](https://github.com/wvwwvwwv/conc-map-bench/tree/Intel).
-- _Interpret the results cautiously as benchmarks usually do not represent real world workloads._
 
 ## [Changelog](https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/CHANGELOG.md)

src/equivalent.rs

@@ -1,6 +1,7 @@
-//! Vendor the [`equivalent`](https://crates.io/crates/equivalent) crate in order to avoid any conflicts.
+//! Vendors the [`equivalent`](https://crates.io/crates/equivalent) crate in order to avoid conflicts.
 
-use std::{borrow::Borrow, cmp::Ordering};
+use std::borrow::Borrow;
+use std::cmp::Ordering;
 
 /// Key equivalence trait.
 ///

src/lib.rs

@@ -1,43 +1,32 @@
 #![deny(missing_docs, warnings, clippy::all, clippy::pedantic)]
 #![doc = include_str!("../README.md")]
 
-pub mod hash_map;
-pub use hash_map::HashMap;
+pub mod bag;
+pub use bag::Bag;
 
-pub mod hash_set;
-pub use hash_set::HashSet;
+#[cfg(not(feature = "equivalent"))]
+mod equivalent;
+pub use equivalent::{Comparable, Equivalent};
 
-pub mod hash_index;
-pub use hash_index::HashIndex;
+mod exit_guard;
 
 pub mod hash_cache;
 pub use hash_cache::HashCache;
 
-mod linked_list;
-pub use linked_list::Entry as LinkedEntry;
-pub use linked_list::LinkedList;
-
-pub mod bag;
-pub use bag::Bag;
-
-pub mod queue;
-pub use queue::Queue;
+pub mod hash_index;
+pub use hash_index::HashIndex;
 
-pub mod stack;
-pub use stack::Stack;
+pub mod hash_map;
+pub use hash_map::HashMap;
 
-pub mod tree_index;
-pub use tree_index::TreeIndex;
+pub mod hash_set;
+pub use hash_set::HashSet;
 
-mod exit_guard;
 mod hash_table;
-mod wait_queue;
-
-#[cfg(not(feature = "equivalent"))]
-mod equivalent;
 
-#[cfg(feature = "serde")]
-mod serde;
+mod linked_list;
+pub use linked_list::Entry as LinkedEntry;
+pub use linked_list::LinkedList;
 
 #[cfg(feature = "loom")]
 mod maybe_std {
@@ -51,6 +40,9 @@ mod maybe_std {
     pub(crate) use std::thread::yield_now;
 }
 
+pub mod queue;
+pub use queue::Queue;
+
 mod range_helper {
     use crate::Comparable;
     use std::ops::Bound::{Excluded, Included, Unbounded};
@@ -76,7 +68,16 @@ mod range_helper {
 /// Re-exports the [`sdd`](https://crates.io/crates/sdd) crate for backward compatibility.
 pub use sdd as ebr;
 
-pub use equivalent::{Comparable, Equivalent};
+#[cfg(feature = "serde")]
+mod serde;
+
+pub mod stack;
+pub use stack::Stack;
 
 #[cfg(test)]
 mod tests;
+
+pub mod tree_index;
+pub use tree_index::TreeIndex;
+
+mod wait_queue;