Merge pull request #105 from moka-rs/api-change1

API stabilization: Smaller core cache API, prefer shorter names for common methods

CHANGELOG.md

@@ -2,27 +2,44 @@
 
 ## Version 0.8.0
 
-### Added
+As a part of stabilizing the cache API, the following cache methods have been renamed:
 
-#### Experimental Additions
+- `get_or_insert_with(K, F)` → `get_with(K, F)`
+- `get_or_try_insert_with(K, F)` → `try_get_with(K, F)`
 
-Please note that the following additions are highly experimental so their APIs will
-be frequently changed in next few releases.
+Old methods are still available but marked as deprecated. They will be removed in a
+future version.
 
-- Add a synchronous cache `moka::dash::Cache`, which uses `dashmap::DashMap` as the
-  internal storage. ([#99][gh-pull-0099])
-- Add iterator to `moka::dash::Cache`. ([#101][gh-pull-0101]) 
+Also `policy` method was added to all caches and `blocking` method was added to
+`future::Cache`. They return a `Policy` struct or `BlockingOp` struct
+respectively. Some uncommon cache methods were moved to these structs, and old
+methods were removed without deprecating.
+
+Please see [#105][gh-pull-0105] for the complete list of the renamed and moved methods.
 
 ### Changed
 
+- API stabilization. (Smaller core cache API, shorter names for common methods)
+  ([#105][gh-pull-0105])
 - Performance related:
-    - Improve performance on `get_or_insert_with`. ([#88][gh-pull-0088])
-    - Avoid to calculate the same hash twice in `get`, `insert`, `invalidate`,
-      etc. ([#90][gh-pull-0090])
+    - Improve performance of `get_with` and `try_get_with`. ([#88][gh-pull-0088])
+    - Avoid to calculate the same hash twice in `get`, `get_with`, `insert`,
+      `invalidate`, etc. ([#90][gh-pull-0090])
 - Update the minimum versions of dependencies:
-    - crossbeam-channel from v0.5.2 to v0.5.4. ([#100][gh-pull-0100])
-    - scheduled-thread-pool to v0.2.5. ([#103][gh-pull-0103]) 
-    - skeptic to v0.13.5. ([#104][gh-pull-0104])
+    - crossbeam-channel to v0.5.4. ([#100][gh-pull-0100])
+    - scheduled-thread-pool to v0.2.5. ([#103][gh-pull-0103])
+    - (dev-dependency) skeptic to v0.13.5. ([#104][gh-pull-0104])
+
+### Added
+
+#### Experimental Additions
+
+- Add a synchronous cache `moka::dash::Cache`, which uses `dashmap::DashMap` as the
+  internal storage. ([#99][gh-pull-0099])
+- Add iterator to `moka::dash::Cache`. ([#101][gh-pull-0101])
+
+Please note that the above additions are highly experimental and their APIs will
+be frequently changed in next few releases.
 
 
 ## Version 0.7.2
@@ -261,6 +278,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-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/
 [gh-pull-0101]: https://github.com/moka-rs/moka/pull/101/

README.md

@@ -99,7 +99,7 @@ moka = { version = "0.8", features = ["future"] }
 
 The thread-safe, synchronous caches are defined in the `sync` module.
 
-Cache entries are manually added using `insert` or `get_or_insert_with` method, and
+Cache entries are manually added using `insert` or `get_with` method, and
 are stored in the cache until either evicted or manually invalidated.
 
 Here's an example of reading and updating a cache by using multiple threads:
@@ -162,9 +162,9 @@ fn main() {
 
 If you want to atomically initialize and insert a value when the key is not present,
 you might want to check [the document][doc-sync-cache] for other insertion methods
-`get_or_insert_with` and `get_or_try_insert_with`.
+`get_with` and `try_get_with`.
 
-[doc-sync-cache]: https://docs.rs/moka/*/moka/sync/struct.Cache.html#method.get_or_insert_with
+[doc-sync-cache]: https://docs.rs/moka/*/moka/sync/struct.Cache.html#method.get_with
 
 
 ## Example: Asynchronous Cache
@@ -255,9 +255,9 @@ async fn main() {
 
 If you want to atomically initialize and insert a value when the key is not present,
 you might want to check [the document][doc-future-cache] for other insertion methods
-`get_or_insert_with` and `get_or_try_insert_with`.
+`get_with` and `try_get_with`.
 
-[doc-future-cache]: https://docs.rs/moka/*/moka/future/struct.Cache.html#method.get_or_insert_with
+[doc-future-cache]: https://docs.rs/moka/*/moka/future/struct.Cache.html#method.get_with
 
 
 ## Avoiding to clone the value at `get`
@@ -468,14 +468,13 @@ $ RUSTFLAGS='--cfg skeptic --cfg trybuild' cargo test \
 - [x] `async` optimized caches. (`v0.2.0`)
 - [x] Size-aware eviction. (`v0.7.0` via
       [#24](https://github.com/moka-rs/moka/pull/24))
-- [ ] API stabilization. (Smaller core cache API, shorter names for frequently
-      used methods)
+- [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))
     - e.g.
     - `get_or_insert_with(K, F)` → `get_with(K, F)`
     - `get_or_try_insert_with(K, F)` → `try_get_with(K, F)`
-    - `get(&Q)` → `get_if_present(&Q)`
     - `blocking_insert(K, V)` → `blocking().insert(K, V)`
-    - `time_to_live()` → `config().time_to_live()`
+    - `time_to_live()` → `policy().time_to_live()`
 - [ ] Cache statistics. (Hit rate, etc.)
 - [ ] Notifications on eviction, etc.
 - [ ] Upgrade TinyLFU to Window-TinyLFU. ([details][tiny-lfu])

src/dash/base_cache.rs

@@ -14,6 +14,7 @@ use crate::{
         housekeeper::{Housekeeper, InnerSync, SyncPace},
         AccessTime, KeyDate, KeyHash, KeyHashDate, KvEntry, ReadOp, ValueEntry, Weigher, WriteOp,
     },
+    Policy,
 };
 
 use crossbeam_channel::{Receiver, Sender, TrySendError};
@@ -185,16 +186,8 @@ where
         self.inner.set_valid_after(now);
     }
 
-    pub(crate) fn max_capacity(&self) -> Option<usize> {
-        self.inner.max_capacity()
-    }
-
-    pub(crate) fn time_to_live(&self) -> Option<Duration> {
-        self.inner.time_to_live()
-    }
-
-    pub(crate) fn time_to_idle(&self) -> Option<Duration> {
-        self.inner.time_to_idle()
+    pub(crate) fn policy(&self) -> Policy {
+        self.inner.policy()
     }
 
     #[cfg(test)]
@@ -516,8 +509,8 @@ where
             .map(|(key, entry)| KvEntry::new(key, entry))
     }
 
-    fn max_capacity(&self) -> Option<usize> {
-        self.max_capacity.map(|n| n as usize)
+    fn policy(&self) -> Policy {
+        Policy::new(self.max_capacity, 1, self.time_to_live, self.time_to_idle)
     }
 
     #[inline]

src/dash/builder.rs

@@ -33,7 +33,7 @@ use std::{
 /// cache.insert(0, "zero");
 ///
 /// // This get() will extend the entry life for another 5 minutes.
-/// cache.get_if_present(&0);
+/// cache.get(&0);
 ///
 /// // Even though we keep calling get(), the entry will expire
 /// // after 30 minutes (TTL) from the insert().
@@ -202,25 +202,27 @@ mod tests {
     fn build_cache() {
         // Cache<char, String>
         let cache = CacheBuilder::new(100).build();
+        let policy = cache.policy();
 
-        assert_eq!(cache.max_capacity(), Some(100));
-        assert_eq!(cache.time_to_live(), None);
-        assert_eq!(cache.time_to_idle(), None);
+        assert_eq!(policy.max_capacity(), Some(100));
+        assert_eq!(policy.time_to_live(), None);
+        assert_eq!(policy.time_to_idle(), None);
 
         cache.insert('a', "Alice");
-        assert_eq!(cache.get_if_present(&'a'), Some("Alice"));
+        assert_eq!(cache.get(&'a'), Some("Alice"));
 
         let cache = CacheBuilder::new(100)
             .time_to_live(Duration::from_secs(45 * 60))
             .time_to_idle(Duration::from_secs(15 * 60))
             .build();
+        let policy = cache.policy();
 
-        assert_eq!(cache.max_capacity(), Some(100));
-        assert_eq!(cache.time_to_live(), Some(Duration::from_secs(45 * 60)));
-        assert_eq!(cache.time_to_idle(), Some(Duration::from_secs(15 * 60)));
+        assert_eq!(policy.max_capacity(), Some(100));
+        assert_eq!(policy.time_to_live(), Some(Duration::from_secs(45 * 60)));
+        assert_eq!(policy.time_to_idle(), Some(Duration::from_secs(15 * 60)));
 
         cache.insert('a', "Alice");
-        assert_eq!(cache.get_if_present(&'a'), Some("Alice"));
+        assert_eq!(cache.get(&'a'), Some("Alice"));
     }
 
     #[test]