Move unsync and experimental dash caches to a new crate called mini-moka

.circleci/config.yml

@@ -17,7 +17,7 @@ jobs:
               --env RUSTFLAGS='--cfg circleci' \
               xd009642/tarpaulin \
               cargo tarpaulin -v \
-                --features 'sync, future, dash' \
+                --features 'sync, future' \
                 --ciserver circle-ci \
                 --coveralls ${COVERALLS_TOKEN} \
                 --timeout 600 \

.cirrus.yml

@@ -48,7 +48,6 @@ linux_arm64_task:
   pin_deps_script: |
     if [ "v$RUST_VERSION" == "v1.51.0" ]; then
       echo 'Pinning some dependencies to specific versions'
-      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 update -p native-tls --precise 0.2.8
@@ -69,23 +68,23 @@ linux_arm64_task:
     # Run tests (release, sync feature, thread-pool test for sync::Cache)
     - cargo test --release --lib --features sync sync::cache::tests::enabling_and_disabling_thread_pools -- --exact --ignored
 
-    # Run tests (release, sync feature, thread-pool test for sync::SegmentCache)
+    # Run tests (release, sync feature, thread-pool test for sync::SegmentedCache)
     - cargo test --release --lib --features sync sync::segment::tests::enabling_and_disabling_thread_pools -- --exact --ignored
 
     # Run tests (sync feature, key lock test for notification)
     - cargo test --release --lib --features sync sync::cache::tests::test_key_lock_used_by_immediate_removal_notifications -- --exact --ignored
 
-    # Run tests (sync feature, drop value after eviction)
+    # Run tests (sync feature, drop value after eviction for sync::Cache)
     - cargo test --release --lib --features sync sync::cache::tests::drop_value_immediately_after_eviction -- --exact --ignored
 
+    # Run tests (sync feature, drop value after eviction for sync::SegmentedCache)
+    - cargo test --release --lib --features sync sync::segment::tests::drop_value_immediately_after_eviction -- --exact --ignored
+
     # Run tests (future feature, but no sync feature)
     - cargo test -j 1  --no-default-features --features 'future, atomic64, quanta' -- --test-threads=$NUM_CPUS
 
     # Run tests (future, sync and logging features)
     - cargo test -j 1  --features 'future, sync, logging' -- --test-threads=$NUM_CPUS
 
-    # Run tests (dash feature, but no sync feature)
-    - cargo test -j 1  --no-default-features --features 'dash, atomic64, quanta' -- --test-threads=$NUM_CPUS
-
   # before_cache_script:
   #   - rm -rf $CARGO_HOME/registry/index

.github/workflows/CI.yml

@@ -67,7 +67,6 @@ jobs:
         # pull-down-cmark >= 0.9.2 requires Rust 2021 edition.
         # once_cell >= 1.15.0 requires Rust 2021 edition.
         run: |
-          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 update -p native-tls --precise 0.2.8
@@ -103,7 +102,7 @@ jobs:
           command: test
           args: --release --lib --features sync sync::cache::tests::enabling_and_disabling_thread_pools -- --exact --ignored
 
-      - name: Run tests (sync feature, thread-pool test for sync::SegmentCache)
+      - name: Run tests (sync feature, thread-pool test for sync::SegmentedCache)
         uses: actions-rs/cargo@v1
         with:
           command: test
@@ -115,26 +114,26 @@ jobs:
           command: test
           args: --release --lib --features sync sync::cache::tests::test_key_lock_used_by_immediate_removal_notifications -- --exact --ignored
 
-      - name: Run tests (sync feature, drop value after eviction)
+      - name: Run tests (sync feature, drop value after eviction for sync::Cache)
         uses: actions-rs/cargo@v1
         with:
           command: test
           args: --release --lib --features sync sync::cache::tests::drop_value_immediately_after_eviction -- --exact --ignored
 
-      - name: Run tests (future feature, but no sync feature)
+      - name: Run tests (sync feature, drop value after eviction for sync::SegmentedCache)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --no-default-features --features 'future, atomic64, quanta'
+          args: --release --lib --features sync sync::segment::tests::drop_value_immediately_after_eviction -- --exact --ignored
 
-      - name: Run tests (future, sync and logging features)
+      - name: Run tests (future feature, but no sync feature)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --features 'future, sync, logging'
+          args: --no-default-features --features 'future, atomic64, quanta'
 
-      - name: Run tests (dash feature, but no sync feature)
+      - name: Run tests (future, sync and logging features)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --no-default-features --features 'dash, atomic64, quanta'
+          args: --features 'future, sync, logging'

.github/workflows/CIQuantaDisabled.yml

@@ -60,7 +60,6 @@ jobs:
         # pull-down-cmark >= 0.9.2 requires Rust 2021 edition.
         # once_cell >= 1.15.0 requires Rust 2021 edition.
         run: |
-          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 update -p native-tls --precise 0.2.8
@@ -95,9 +94,3 @@ jobs:
         with:
           command: test
           args: --no-default-features --features 'sync, future, atomic64, logging'
-
-      - name: Run tests (dash feature, but no quanta and sync features)
-        uses: actions-rs/cargo@v1
-        with:
-          command: test
-          args: --no-default-features --features 'dash, atomic64'

.github/workflows/Lints.yml

@@ -43,7 +43,9 @@ jobs:
         if: ${{ matrix.rust == 'stable' || matrix.rust == 'beta' }}
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          args: --lib --tests --all-features --all-targets -- -D warnings
+          # Specify individual features until we remove `dash` feature.
+          # args: --lib --tests --all-features --all-targets -- -D warnings
+          args: --lib --tests --features 'future, logging, unstable-debug-counters' --all-targets -- -D warnings
 
       - name: Run Rustfmt
         uses: actions-rs/cargo@v1

.github/workflows/LinuxCrossCompileTest.yml

@@ -76,10 +76,3 @@ jobs:
           use-cross: true
           command: test
           args: --release --features future --target ${{ matrix.platform.target }} ${{ matrix.platform.cargo-opts }}
-
-      - name: Run tests (dash feature)
-        uses: actions-rs/cargo@v1
-        with:
-          use-cross: true
-          command: test
-          args: --release --features dash --target ${{ matrix.platform.target }} ${{ matrix.platform.cargo-opts }}

.github/workflows/Skeptic.yml

@@ -46,27 +46,27 @@ jobs:
         env:
           RUSTFLAGS: '--cfg skeptic'
 
-      - name: Run tests (release, future and dash)
+      - name: Run tests (release, sync and future)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --release --features 'sync, future, dash'
+          args: --release --features 'sync, future'
         env:
           RUSTFLAGS: '--cfg skeptic'
 
-      - name: Run tests (sync, future and dash, without atomic64 and quanta)
+      - name: Run tests (sync and future, without atomic64 and quanta)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --release --no-default-features --features 'sync, future, dash'
+          args: --release --no-default-features --features 'sync, future'
         env:
           RUSTFLAGS: '--cfg skeptic'
 
-      - name: Run compile error tests (sync, future and dash features, trybuild)
+      - name: Run compile error tests (sync and future features, trybuild)
         uses: actions-rs/cargo@v1
         if: ${{ matrix.rust == 'stable' }}
         with:
           command: test
-          args: ui_trybuild --release --features 'sync, future, dash'
+          args: ui_trybuild --release --features 'sync, future'
         env:
           RUSTFLAGS: '--cfg trybuild'

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-    "rust-analyzer.cargo.features": ["future", "dash", "logging", "unstable-debug-counters"],
+    "rust-analyzer.cargo.features": ["future", "logging", "unstable-debug-counters"],
     "rust-analyzer.server.extraEnv": {
         "CARGO_TARGET_DIR": "target/ra"
     },

Cargo.toml

@@ -25,10 +25,12 @@ sync = ["crossbeam-epoch", "thiserror", "uuid"]
 # Enable this feature to use `moka::future::Cache`.
 future = ["crossbeam-epoch", "thiserror", "uuid", "async-io", "async-lock", "futures-util"]
 
-# Enable this feature to use **experimental** `moka::dash::Cache`.
-# Please note that the APIs for this feature will be frequently changed in next
-# few releases.
-dash = ["dashmap"]
+# Removed from "moka" (v0.10.0): `moka::dash::Cache` has been moved to a separate
+# crate called "mini-moka" and the module `dash` was renamed to `sync` there. Please
+# use `mini_moka::sync::Cache` instead.
+# https://docs.rs/mini-moka/latest/mini_moka/sync/struct.Cache.html
+# https://crates.io/crates/mini-moka
+dash = []
 
 # Enable this feature to activate optional logging from caches.
 # Currently cache will emit log only when it encounters a panic in user provided
@@ -71,9 +73,6 @@ quanta = { version = "0.10.0", optional = true }
 thiserror = { version = "1.0", optional = true }
 uuid = { version = "1.1", features = ["v4"], optional = true }
 
-# Optional dependencies (dashmap)
-dashmap = { version = "5.2", optional = true }
-
 # Optional dependencies (future)
 async-io = { version = "1.4", optional = true }
 async-lock = { version = "2.4", optional = true }
@@ -105,7 +104,7 @@ rustc_version = "0.4.0"
 # https://docs.rs/about/metadata
 [package.metadata.docs.rs]
 # Build the doc with some features enabled.
-features = ["future", "dash"]
+features = ["future"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 # ----------------------------------

README.md

@@ -12,8 +12,7 @@ Moka is a fast, concurrent cache library for Rust. Moka is inspired by the
 [Caffeine][caffeine-git] library for Java.
 
 Moka provides cache implementations on top of hash maps. They support full
-concurrency of retrievals and a high expected concurrency for updates. Moka also
-provides a non-thread-safe cache implementation for single thread applications.
+concurrency of retrievals and a high expected concurrency for updates.
 
 All caches perform a best-effort bounding of a hash map using an entry replacement
 algorithm to determine which entries to evict when the capacity is exceeded.
@@ -38,6 +37,9 @@ algorithm to determine which entries to evict when the capacity is exceeded.
 
 ## Features
 
+Moka provides a rich and flexible feature set while maintaining high hit ratio and a
+high level of concurrency for concurrent access.
+
 - Thread-safe, highly concurrent in-memory cache implementations:
     - Synchronous caches that can be shared across OS threads.
     - An asynchronous (futures aware) cache that can be accessed inside and outside
@@ -56,15 +58,37 @@ algorithm to determine which entries to evict when the capacity is exceeded.
 - Supports eviction listener, a callback function that will be called when an entry
   is removed from the cache.
 
-Moka provides a rich and flexible feature set while maintaining high hit ratio and a
-high level of concurrency for concurrent access. However, it may not be as fast as
-other caches, especially those that focus on much smaller feature sets.
-
-If you do not need features like: time to live, size aware eviction, and eviction
-listener, you may want to take a look at the [Quick Cache][quick-cache] crate.
+### Choosing the right cache for your use case
+
+No cache implementation is perfect for every use cases. Moka is a complex software
+and can be overkill for your use case. Sometimes simpler caches like
+[Mini Moka][mini-moka-crate] or [Quick Cache][quick-cache] might be a better fit.
+
+The following table shows the trade-offs between the different cache implementations:
+
+| Feature | Moka v0.10 | Mini Moka v0.10 | Quick Cache v0.1 |
+|:------- |:---- |:--------- |:----------- |
+| Thread-safe, sync cache | ✅ | ✅ | ✅ |
+| Thread-safe, async cache | ✅ | ❌ | ❌ |
+| Non-concurrent cache | ❌ | ✅ | ✅ |
+| Bounded by the maximum number of entries | ✅ | ✅ | ✅ |
+| Bounded by the total weighted size of entries | ✅ | ✅ | ❌ |
+| Near optimal hit ratio | ✅ TinyLFU | ✅ TinyLFU | ✅ CLOCK-Pro |
+| Expiration policies | ✅ | ✅ | ❌ |
+| Eviction listener | ✅ | ❌ | ❌ |
+| Per-key, atomic insertion | ✅ `get_with` family methods | ❌ | ❌ |
+| Lock-free, concurrent iterator | ✅ | ❌ | ❌ |
+| Lock-per-shard, concurrent iterator | ❌ | ✅ | ❌ |
+
+| Performance | Moka v0.10 | Mini Moka v0.10 | Quick Cache v0.1 |
+|:------- |:---- |:--------- |:----------- |
+| Small overhead compared to a concurrent hash table | ❌ | ❌ | ✅ |
+| Does not use background threads | ❌ | ✅ | ✅ |
+| Small dependency tree | ❌ | ✅ | ✅ |
 
 [tiny-lfu]: https://github.com/moka-rs/moka/wiki#admission-and-eviction-policies
 [quick-cache]: https://crates.io/crates/quick_cache
+[mini-moka-crate]: https://crates.io/crates/mini-moka
 
 ## Moka in Production
 
@@ -88,10 +112,22 @@ routers. Here are some highlights:
 
 - [CHANGELOG.md](https://github.com/moka-rs/moka/blob/master/CHANGELOG.md)
 
+The `unsync::Cache` and `dash::Cache` have been moved to [Mini Moka][mini-moka-crate]
+crate:
+
+- Non concurrent cache for single threaded applications:
+    - `moka::unsync::Cache` → [`mini_moka::unsync::Cache`][unsync-cache-struct]
+- Experimental, thread-safe, synchronous cache:
+    - `moka::dash::Cache` →→ [`mini_moka::sync::Cache`][dash-cache-struct]
+
+[unsync-cache-struct]: https://docs.rs/mini-moka/latest/mini_moka/unsync/struct.Cache.html
+[dash-cache-struct]: https://docs.rs/mini-moka/latest/mini_moka/sync/struct.Cache.html
+
 
 ## Table of Contents
 
 - [Features](#features)
+    - [Choosing the right cache for your use case](#choosing-the-right-cache-for-your-use-case)
 - [Moka in Production](#moka-in-production)
 - [Change Log](#change-log)
 - [Usage](#usage)

src/common.rs

@@ -1,6 +1,6 @@
 use std::convert::TryInto;
 
-#[cfg(any(feature = "sync", feature = "future", feature = "dash"))]
+#[cfg(any(feature = "sync", feature = "future"))]
 pub(crate) mod concurrent;
 
 #[cfg(any(feature = "sync", feature = "future"))]