Merge pull request #161 from moka-rs/next

Merge branch `next` into `master` (v0.9.0)

.circleci/config.yml

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

.github/workflows/CI.yml

@@ -70,25 +70,32 @@ jobs:
           command: tree
           args: --features 'future, dash'
 
-      - name: Build (no features)
+      - name: Run tests (debug, sync feature)
         uses: actions-rs/cargo@v1
         with:
-          command: build
+          command: test
+          args: --features sync
+
+      - name: Run tests (release, sync feature)
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --release --features sync
 
-      - name: Run tests (release, no features)
+      - name: Run tests (future feature, but no sync feature)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --release
+          args: --no-default-features --features 'future, atomic64, quanta'
 
-      - name: Run tests (future feature)
+      - name: Run tests (future, sync and logging features)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --features future
+          args: --features 'future, sync, logging'
 
-      - name: Run tests (dash feature)
+      - name: Run tests (dash feature, but no sync feature)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --features dash
+          args: --no-default-features --features 'dash, atomic64, quanta'

.github/workflows/CIQuantaDisabled.yml

@@ -64,25 +64,31 @@ jobs:
           cargo update -p native-tls --precise 0.2.8
           cargo update -p async-global-executor --precise 2.0.4
 
-      - name: Build (no quanta feature)
+      - name: Run tests (debug, but no quanta feature)
         uses: actions-rs/cargo@v1
         with:
-          command: build
-          args: --no-default-features --features atomic64
+          command: test
+          args: --no-default-features --features 'sync, atomic64'
 
-      - name: Run tests (release, no quanta feature)
+      - name: Run tests (release, but no quanta feature)
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --release --no-default-features --features atomic64
+          args: --release --no-default-features --features 'sync, atomic64'
 
-      - name: Run tests (future feature, but no quanta feature)
+      - name: Run tests (future feature, but no quanta and sync features)
         uses: actions-rs/cargo@v1
         with:
           command: test
           args: --no-default-features --features 'future, atomic64'
 
-      - name: Run tests (dash feature, but no quanta feature)
+      - name: Run tests (future, sync and logging features, but no quanta feature)
+        uses: actions-rs/cargo@v1
+        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

.github/workflows/LinuxCrossCompileTest.yml

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

.github/workflows/Skeptic.yml

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

.vscode/settings.json

@@ -1,8 +1,9 @@
 {
-    "rust-analyzer.cargo.features": ["future", "dash", "unstable-debug-counters"],
+    "rust-analyzer.cargo.features": ["future", "dash", "logging", "unstable-debug-counters"],
     "rust-analyzer.server.extraEnv": {
         "CARGO_TARGET_DIR": "target/ra"
     },
+    "editor.rulers": [85],
     "cSpell.words": [
         "aarch",
         "actix",

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Moka Cache — Change Log
 
+## Version 0.9.0
+
+### Added
+
+- Add support for eviction listener to the following caches ([#145][gh-pull-0145]).
+  Eviction listener is a callback function that will be called when an entry is
+  removed from the cache.
+    - `sync::Cache`
+    - `sync::SegmentedCache`
+    - `future::Cache`
+- Add a crate feature `sync` for enabling and disabling `sync` caches.
+  ([#143][gh-pull-0143])
+    - This feature is enabled by default.
+    - When using experimental `dash` cache, opting out of `sync` will reduce the
+      number of dependencies.
+- Add a crate feature `logging` to enable optional log crate dependency.
+  ([#159][gh-pull-0159])
+    - Currently log will be emitted only when an eviction listener has panicked.
+
+
 ## Version 0.8.6
 
 ### Fixed
@@ -392,6 +412,9 @@ The minimum supported Rust version (MSRV) is now 1.51.0 (2021-03-25).
 [gh-issue-0034]: https://github.com/moka-rs/moka/issues/34/
 [gh-issue-0031]: https://github.com/moka-rs/moka/issues/31/
 
+[gh-pull-0159]: https://github.com/moka-rs/moka/pull/159/
+[gh-pull-0145]: https://github.com/moka-rs/moka/pull/145/
+[gh-pull-0143]: https://github.com/moka-rs/moka/pull/143/
 [gh-pull-0138]: https://github.com/moka-rs/moka/pull/138/
 [gh-pull-0137]: https://github.com/moka-rs/moka/pull/137/
 [gh-pull-0133]: https://github.com/moka-rs/moka/pull/133/

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "moka"
-version = "0.8.6"
+version = "0.9.0"
 edition = "2018"
 rust-version = "1.51"
 
@@ -16,16 +16,25 @@ exclude = [".circleci", ".devcontainer", ".github", ".gitpod.yml", ".vscode"]
 build = "build.rs"
 
 [features]
-default = ["atomic64", "quanta"]
+default = ["sync", "atomic64", "quanta"]
+
+# This feature is enabled by default. Disable it when you do not need
+# `moka::sync::{Cache, SegmentedCache}`
+sync = ["crossbeam-epoch", "thiserror", "uuid"]
 
 # Enable this feature to use `moka::future::Cache`.
-future = ["async-io", "async-lock", "futures-util"]
+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"]
 
+# Enable this feature to activate optional logging from caches.
+# Currently cache will emit log only when it encounters a panic in user provided
+# callback closure.
+logging = ["log"]
+
 # This feature is enabled by default. Disable it when the target platform does not
 # support `std::sync::atomic::AtomicU64`. (e.g. `armv5te-unknown-linux-musleabi`
 # or `mips-unknown-linux-musl`)
@@ -43,23 +52,23 @@ crossbeam-utils = "0.8"
 num_cpus = "1.13"
 once_cell = "1.7"
 parking_lot = "0.12"
-scheduled-thread-pool = "0.2.5"
+scheduled-thread-pool = "0.2.6"
 smallvec = "1.8"
 tagptr = "0.2"
-thiserror = "1.0"
-uuid = { version = "1.1", features = ["v4"] }
-
-# Although v0.8.2 is not the current version (v0.9.x), we will keep using it until
-# we perform enough tests to get conformable with memory safety.
-# See: https://github.com/moka-rs/moka/issues/34
-crossbeam-epoch = "0.8.2"
 
 # Opt-out serde and stable_deref_trait features
 # https://github.com/Manishearth/triomphe/pull/5
-triomphe = { version = "0.1", default-features = false }
+triomphe = { version = "0.1.3", default-features = false }
 
-# Optional dependencies (quanta, enabled by default)
+# Optional dependencies (enabled by default)
 quanta = { version = "0.10.0", optional = true }
+thiserror = { version = "1.0", optional = true }
+uuid = { version = "1.1", features = ["v4"], optional = true }
+
+# Although v0.8.2 is not the current version (v0.9.x), we will keep using it until
+# we perform enough tests to get conformable with memory safety.
+# See: https://github.com/moka-rs/moka/issues/34
+crossbeam-epoch = { version = "0.8.2", optional = true }
 
 # Optional dependencies (dashmap)
 dashmap = { version = "5.2", optional = true }
@@ -69,13 +78,18 @@ async-io = { version = "1.4", optional = true }
 async-lock = { version = "2.4", optional = true }
 futures-util = { version = "0.3", optional = true }
 
+# Optional dependencies (logging)
+log = { version = "0.4", optional = true }
+
 [dev-dependencies]
 actix-rt = { version = "2.7", default-features = false }
+anyhow = "1.0"
 async-std = { version = "1.11", features = ["attributes"] }
+env_logger = "0.9"
 getrandom = "0.2"
 reqwest = "0.11.11"
 skeptic = "0.13"
-tokio = { version = "1.19", features = ["rt-multi-thread", "macros", "sync", "time" ] }
+tokio = { version = "1.19", features = ["fs", "macros", "rt-multi-thread", "sync", "time" ] }
 
 [target.'cfg(trybuild)'.dev-dependencies]
 trybuild = "1.0"

README.md

@@ -53,6 +53,9 @@ algorithm to determine which entries to evict when the capacity is exceeded.
 - Supports expiration policies:
     - Time to live
     - Time to idle
+- Supports eviction listener, a callback function that will be called when an entry
+  is removed from the cache.
+
 
 [tiny-lfu]: https://github.com/moka-rs/moka/wiki#admission-and-eviction-policies
 
@@ -528,20 +531,23 @@ $ cargo +nightly -Z unstable-options --config 'build.rustdocflags="--cfg docsrs"
 ## Road Map
 
 - [x] `async` optimized caches. (`v0.2.0`)
-- [x] Size-aware eviction. (`v0.7.0` via
-      [#24](https://github.com/moka-rs/moka/pull/24))
-- [X] API stabilization. (Smaller core cache API, shorter names for frequently
-      used methods) (`v0.8.0` via [#105](https://github.com/moka-rs/moka/pull/105))
+- [x] Size-aware eviction. (`v0.7.0` via [#24][gh-pull-024])
+- [x] API stabilization. (Smaller core cache API, shorter names for frequently
+      used methods) (`v0.8.0` via [#105][gh-pull-105])
     - e.g.
     - `get_or_insert_with(K, F)` → `get_with(K, F)`
     - `get_or_try_insert_with(K, F)` → `try_get_with(K, F)`
     - `blocking_insert(K, V)` → `blocking().insert(K, V)`
     - `time_to_live()` → `policy().time_to_live()`
-- [ ] Notifications on eviction, etc.
+- [x] Notifications on eviction. (`v0.9.0` via [#145][gh-pull-145])
 - [ ] Cache statistics. (Hit rate, etc.)
 - [ ] Upgrade TinyLFU to Window-TinyLFU. ([details][tiny-lfu])
 - [ ] The variable (per-entry) expiration, using a hierarchical timer wheel.
 
+[gh-pull-024]: https://github.com/moka-rs/moka/pull/24
+[gh-pull-105]: https://github.com/moka-rs/moka/pull/105
+[gh-pull-145]: https://github.com/moka-rs/moka/pull/145
+
 
 ## About the Name
 

src/cht/segment.rs

@@ -193,6 +193,10 @@ impl<K, V, S> HashMap<K, V, S> {
         }
     }
 
+    pub(crate) fn actual_num_segments(&self) -> usize {
+        self.segments.len()
+    }
+
     /// Returns the number of elements in the map.
     ///
     /// # Safety
@@ -560,10 +564,6 @@ 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> {

src/common.rs

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

src/common/concurrent.rs

@@ -77,12 +77,12 @@ impl<K> KeyDate<K> {
         &self.key
     }
 
-    // #[cfg(any(feature = "sync", feature = "future"))]
+    #[cfg(any(feature = "sync", feature = "future"))]
     pub(crate) fn last_modified(&self) -> Option<Instant> {
         self.entry_info.last_modified()
     }
 
-    // #[cfg(any(feature = "sync", feature = "future"))]
+    #[cfg(any(feature = "sync", feature = "future"))]
     pub(crate) fn is_dirty(&self) -> bool {
         self.entry_info.is_dirty()
     }

src/common/concurrent/thread_pool.rs

@@ -5,20 +5,24 @@ use std::{collections::HashMap, sync::Arc};
 
 static REGISTRY: Lazy<ThreadPoolRegistry> = Lazy::new(ThreadPoolRegistry::default);
 
-#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
-// #[cfg_attr(any(feature = "sync", feature = "future"), derive(Debug))]
+#[derive(Clone, Copy, Hash, PartialEq, Eq)]
+#[cfg_attr(any(feature = "sync", feature = "future"), derive(Debug))]
 pub(crate) enum PoolName {
     Housekeeper,
-    // #[cfg(any(feature = "sync", feature = "future"))]
+    #[cfg(any(feature = "sync", feature = "future"))]
     Invalidator,
+    #[cfg(any(feature = "sync", feature = "future"))]
+    RemovalNotifier,
 }
 
 impl PoolName {
     fn thread_name_template(&self) -> &'static str {
         match self {
             PoolName::Housekeeper => "moka-housekeeper-{}",
-            // #[cfg(any(feature = "sync", feature = "future"))]
+            #[cfg(any(feature = "sync", feature = "future"))]
             PoolName::Invalidator => "moka-invalidator-{}",
+            #[cfg(any(feature = "sync", feature = "future"))]
+            PoolName::RemovalNotifier => "moka-notifier-{}",
         }
     }
 }

src/common/deque.rs

@@ -116,7 +116,7 @@ impl<T> Deque<T> {
         self.region
     }
 
-    // #[cfg(any(test, feature = "sync", feature = "future"))]
+    #[cfg(any(test, feature = "sync", feature = "future"))]
     pub(crate) fn len(&self) -> usize {
         self.len
     }