Merge pull request #216 from moka-rs/build-with-hasher-doc

doc: Add examples for `build_with_hasher` method of cache builders

.cirrus.yml

@@ -49,6 +49,8 @@ linux_arm64_task:
   pin_deps_script: |
     if [ "v$RUST_VERSION" == "v1.51.0" ]; then
       echo 'Pinning some dependencies to specific versions'
+      rm -f Cargo.lock
+      sed -i 's/ahash = ".*"/ahash = "=0.7.6"/g' Cargo.toml
       cargo update -p dashmap --precise 5.2.0
       cargo update -p indexmap --precise 1.8.2
       cargo update -p hashbrown --precise 0.11.2

.github/workflows/CI.yml

@@ -73,6 +73,8 @@ jobs:
         # pull-down-cmark >= 0.9.2 requires Rust 2021 edition.
         # once_cell >= 1.15.0 requires Rust 2021 edition.
         run: |
+          rm -f Cargo.lock
+          sed -i 's/ahash = ".*"/ahash = "=0.7.6"/g' Cargo.toml
           cargo update -p dashmap --precise 5.2.0
           cargo update -p indexmap --precise 1.8.2
           cargo update -p hashbrown --precise 0.11.2

.github/workflows/CIQuantaDisabled.yml

@@ -66,6 +66,8 @@ jobs:
         # pull-down-cmark >= 0.9.2 requires Rust 2021 edition.
         # once_cell >= 1.15.0 requires Rust 2021 edition.
         run: |
+          rm -f Cargo.lock
+          sed -i 's/ahash = ".*"/ahash = "=0.7.6"/g' Cargo.toml
           cargo update -p dashmap --precise 5.2.0
           cargo update -p indexmap --precise 1.8.2
           cargo update -p hashbrown --precise 0.11.2

Cargo.toml

@@ -84,6 +84,7 @@ log = { version = "0.4", optional = true }
 
 [dev-dependencies]
 actix-rt = { version = "2.7", default-features = false }
+ahash = "0.8.3"
 anyhow = "1.0.19"
 async-std = { version = "1.11", features = ["attributes"] }
 env_logger = "0.9"

README.md

@@ -414,7 +414,7 @@ attacks such as HashDoS.
 
 The hashing algorithm can be replaced on a per-`Cache` basis using the
 `build_with_hasher` method of the `CacheBuilder`. Many alternative algorithms are
-available on crates.io, such as the [aHash][ahash-crate] crate.
+available on crates.io, such as the [AHash][ahash-crate] crate.
 
 [ahash-crate]: https://crates.io/crates/ahash
 

src/cht/segment.rs

@@ -62,7 +62,7 @@ use crossbeam_epoch::Atomic;
 /// [`default`], [`with_hasher`], [`with_capacity_and_hasher`],
 /// [`with_num_segments_and_hasher`], and
 /// [`with_num_segments_capacity_and_hasher`] methods. Many alternative
-/// algorithms are available on crates.io, such as the [`aHash`] crate.
+/// algorithms are available on crates.io, such as the [`AHash`] crate.
 ///
 /// The number of segments can be specified on a per-`HashMap` basis using the
 /// [`with_num_segments`], [`with_num_segments_and_capacity`],
@@ -88,7 +88,7 @@ use crossbeam_epoch::Atomic;
 /// the [`Eq`] trait, changes while it is in the map. This is normally only
 /// possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code.
 ///
-/// [`aHash`]: https://crates.io/crates/ahash
+/// [`AHash`]: https://crates.io/crates/ahash
 /// [`default`]: #method.default
 /// [`with_hasher`]: #method.with_hasher
 /// [`with_capacity`]: #method.with_capacity

src/dash/cache.rs

@@ -225,7 +225,7 @@ use std::{
 /// The hashing algorithm can be replaced on a per-`Cache` basis using the
 /// [`build_with_hasher`][build-with-hasher-method] method of the
 /// `CacheBuilder`. Many alternative algorithms are available on crates.io, such
-/// as the [aHash][ahash-crate] crate.
+/// as the [AHash][ahash-crate] crate.
 ///
 /// [build-with-hasher-method]: ./struct.CacheBuilder.html#method.build_with_hasher
 /// [ahash-crate]: https://crates.io/crates/ahash

src/future/builder.rs

@@ -126,7 +126,78 @@ where
         )
     }
 
-    /// Builds a `Cache<K, V, S>`, with the given `hasher`.
+    /// Builds a `Cache<K, V, S>` with the given `hasher` of type `S`.
+    ///
+    /// # Examples
+    ///
+    /// This example uses AHash hasher from [AHash][ahash-crate] crate.
+    ///
+    /// [ahash-crate]: https://crates.io/crates/ahash
+    ///
+    /// ```rust
+    /// // Cargo.toml
+    /// // [dependencies]
+    /// // ahash = "0.8"
+    /// // moka = { version = ..., features = ["future"] }
+    /// // tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
+    ///
+    /// use moka::future::Cache;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     // The type of this cache is: Cache<i32, String, ahash::RandomState>
+    ///     let cache = Cache::builder()
+    ///         .max_capacity(100)
+    ///         .build_with_hasher(ahash::RandomState::default());
+    ///     cache.insert(1, "one".to_string()).await;
+    /// }
+    /// ```
+    ///
+    /// Note: If you need to add a type annotation to your cache, you must use the
+    /// form of `Cache<K, V, S>` instead of `Cache<K, V>`. That `S` is the type of
+    /// the build hasher, and its default is the `RandomState` from
+    /// `std::collections::hash_map` module . If you use a different build hasher,
+    /// you must specify `S` explicitly.
+    ///
+    /// Here is a good example:
+    ///
+    /// ```rust
+    /// # use moka::future::Cache;
+    /// # #[tokio::main]
+    /// # async fn main() {
+    /// # let cache = Cache::builder()
+    /// #     .build_with_hasher(ahash::RandomState::default());
+    /// struct Good {
+    ///     // Specifying the type in Cache<K, V, S> format.
+    ///     cache: Cache<i32, String, ahash::RandomState>,
+    /// }
+    ///
+    /// // Storing the cache from above example. This should compile.
+    /// Good { cache };
+    /// # }
+    /// ```
+    ///
+    /// Here is a bad example. This struct cannot store the above cache because it
+    /// does not specify `S`:
+    ///
+    /// ```compile_fail
+    /// # use moka::future::Cache;
+    /// # #[tokio::main]
+    /// # async fn main() {
+    /// # let cache = Cache::builder()
+    /// #     .build_with_hasher(ahash::RandomState::default());
+    /// struct Bad {
+    ///     // Specifying the type in Cache<K, V> format.
+    ///     cache: Cache<i32, String>,
+    /// }
+    ///
+    /// // This should not compile.
+    /// Bad { cache };
+    /// // => error[E0308]: mismatched types
+    /// //    expected struct `std::collections::hash_map::RandomState`,
+    /// //       found struct `ahash::RandomState`
+    /// # }
+    /// ```
     ///
     /// # Panics
     ///

src/future/cache.rs

@@ -500,7 +500,7 @@ use std::{
 /// The hashing algorithm can be replaced on a per-`Cache` basis using the
 /// [`build_with_hasher`][build-with-hasher-method] method of the `CacheBuilder`.
 /// Many alternative algorithms are available on crates.io, such as the
-/// [aHash][ahash-crate] crate.
+/// [AHash][ahash-crate] crate.
 ///
 /// [build-with-hasher-method]: ./struct.CacheBuilder.html#method.build_with_hasher
 /// [ahash-crate]: https://crates.io/crates/ahash

src/sync/builder.rs

@@ -153,10 +153,68 @@ where
         )
     }
 
-    /// Builds a `Cache<K, V, S>`, with the given `hasher`.
-    ///
-    /// If you want to build a `SegmentedCache<K, V>`, call `segments` method  before
-    /// calling this method.
+    /// Builds a `Cache<K, V, S>` with the given `hasher` of type `S`.
+    ///
+    /// # Examples
+    ///
+    /// This example uses AHash hasher from [AHash][ahash-crate] crate.
+    ///
+    /// [ahash-crate]: https://crates.io/crates/ahash
+    ///
+    /// ```rust
+    /// // Cargo.toml
+    /// // [dependencies]
+    /// // ahash = "0.8"
+    /// // moka = ...
+    ///
+    /// use moka::sync::Cache;
+    ///
+    /// // The type of this cache is: Cache<i32, String, ahash::RandomState>
+    /// let cache = Cache::builder()
+    ///     .max_capacity(100)
+    ///     .build_with_hasher(ahash::RandomState::default());
+    /// cache.insert(1, "one".to_string());
+    /// ```
+    ///
+    /// Note: If you need to add a type annotation to your cache, you must use the
+    /// form of `Cache<K, V, S>` instead of `Cache<K, V>`. That `S` is the type of
+    /// the build hasher, and its default is the `RandomState` from
+    /// `std::collections::hash_map` module . If you use a different build hasher,
+    /// you must specify `S` explicitly.
+    ///
+    /// Here is a good example:
+    ///
+    /// ```rust
+    /// # use moka::sync::Cache;
+    /// # let cache = Cache::builder()
+    /// #     .build_with_hasher(ahash::RandomState::default());
+    /// struct Good {
+    ///     // Specifying the type in Cache<K, V, S> format.
+    ///     cache: Cache<i32, String, ahash::RandomState>,
+    /// }
+    ///
+    /// // Storing the cache from above example. This should compile.
+    /// Good { cache };
+    /// ```
+    ///
+    /// Here is a bad example. This struct cannot store the above cache because it
+    /// does not specify `S`:
+    ///
+    /// ```compile_fail
+    /// # use moka::sync::Cache;
+    /// # let cache = Cache::builder()
+    /// #     .build_with_hasher(ahash::RandomState::default());
+    /// struct Bad {
+    ///     // Specifying the type in Cache<K, V> format.
+    ///     cache: Cache<i32, String>,
+    /// }
+    ///
+    /// // This should not compile.
+    /// Bad { cache };
+    /// // => error[E0308]: mismatched types
+    /// //    expected struct `std::collections::hash_map::RandomState`,
+    /// //       found struct `ahash::RandomState`
+    /// ```
     ///
     /// # Panics
     ///
@@ -218,10 +276,69 @@ where
         )
     }
 
-    /// Builds a `SegmentedCache<K, V, S>`, with the given `hasher`.
-    ///
-    /// If you want to build a `Cache<K, V>`, do not call `segments` method before
-    /// calling this method.
+    /// Builds a `SegmentedCache<K, V, S>` with the given `hasher`.
+    ///
+    ///
+    /// # Examples
+    ///
+    /// This example uses AHash hasher from [AHash][ahash-crate] crate.
+    ///
+    /// [ahash-crate]: https://crates.io/crates/ahash
+    ///
+    /// ```rust
+    /// // Cargo.toml
+    /// // [dependencies]
+    /// // ahash = "0.8"
+    /// // moka = ...
+    ///
+    /// use moka::sync::SegmentedCache;
+    ///
+    /// // The type of this cache is: SegmentedCache<i32, String, ahash::RandomState>
+    /// let cache = SegmentedCache::builder(4)
+    ///     .max_capacity(100)
+    ///     .build_with_hasher(ahash::RandomState::default());
+    /// cache.insert(1, "one".to_string());
+    /// ```
+    ///
+    /// Note: If you need to add a type annotation to your cache, you must use the
+    /// form of `SegmentedCache<K, V, S>` instead of `SegmentedCache<K, V>`. That `S`
+    /// is the type of the build hasher, whose default is the `RandomState` from
+    /// `std::collections::hash_map` module . If you use a different build hasher,
+    /// you must specify `S` explicitly.
+    ///
+    /// Here is a good example:
+    ///
+    /// ```rust
+    /// # use moka::sync::SegmentedCache;
+    /// # let cache = SegmentedCache::builder(4)
+    /// #     .build_with_hasher(ahash::RandomState::default());
+    /// struct Good {
+    ///     // Specifying the type in SegmentedCache<K, V, S> format.
+    ///     cache: SegmentedCache<i32, String, ahash::RandomState>,
+    /// }
+    ///
+    /// // Storing the cache from above example. This should compile.
+    /// Good { cache };
+    /// ```
+    ///
+    /// Here is a bad example. This struct cannot store the above cache because it
+    /// does not specify `S`:
+    ///
+    /// ```compile_fail
+    /// # use moka::sync::SegmentedCache;
+    /// # let cache = SegmentedCache::builder(4)
+    /// #     .build_with_hasher(ahash::RandomState::default());
+    /// struct Bad {
+    ///     // Specifying the type in SegmentedCache<K, V> format.
+    ///     cache: SegmentedCache<i32, String>,
+    /// }
+    ///
+    /// // This should not compile.
+    /// Bad { cache };
+    /// // => error[E0308]: mismatched types
+    /// //    expected struct `std::collections::hash_map::RandomState`,
+    /// //       found struct `ahash::RandomState`
+    /// ```
     ///
     /// # Panics
     ///

src/sync/cache.rs

@@ -668,7 +668,7 @@ use std::{
 /// The hashing algorithm can be replaced on a per-`Cache` basis using the
 /// [`build_with_hasher`][build-with-hasher-method] method of the `CacheBuilder`.
 /// Many alternative algorithms are available on crates.io, such as the
-/// [aHash][ahash-crate] crate.
+/// [AHash][ahash-crate] crate.
 ///
 /// [build-with-hasher-method]: ./struct.CacheBuilder.html#method.build_with_hasher
 /// [ahash-crate]: https://crates.io/crates/ahash

src/unsync/cache.rs

@@ -159,7 +159,7 @@ type CacheStore<K, V, S> = std::collections::HashMap<Rc<K>, ValueEntry<K, V>, S>
 /// The hashing algorithm can be replaced on a per-`Cache` basis using the
 /// [`build_with_hasher`][build-with-hasher-method] method of the
 /// `CacheBuilder`. Many alternative algorithms are available on crates.io, such
-/// as the [aHash][ahash-crate] crate.
+/// as the [AHash][ahash-crate] crate.
 ///
 /// [build-with-hasher-method]: ./struct.CacheBuilder.html#method.build_with_hasher
 /// [ahash-crate]: https://crates.io/crates/ahash