Add the "entry" and "entry_by_ref" APIs

src/common.rs

@@ -6,6 +6,9 @@ pub(crate) mod concurrent;
 #[cfg(any(feature = "sync", feature = "future"))]
 pub(crate) mod error;
 
+#[cfg(any(feature = "sync", feature = "future"))]
+pub(crate) mod entry;
+
 pub(crate) mod builder_utils;
 pub(crate) mod deque;
 pub(crate) mod frequency_sketch;

src/common/concurrent/thread_pool.rs

@@ -71,7 +71,12 @@ impl ThreadPoolRegistry {
                 // and insert a new pool.
                 let mut pools = REGISTRY.pools.write();
                 pools.entry(name).or_insert_with(|| {
-                    // Some platforms may return 0. In that case, use 1.
+                    // TODO: When we upgrade the MSRV to 1.59 (2022-02-24) or newer,
+                    // replace num_cpus crate with `thread::available_parallelism` in
+                    // std.
+                    //
+                    // NOTE: On some platforms, `num_cpus::get` may return 0. In that
+                    // case, use 1.
                     // https://github.com/moka-rs/moka/pull/39#issuecomment-916888859
                     // https://github.com/seanmonstar/num_cpus/issues/69
                     let num_threads = num_cpus::get().max(1);

src/common/entry.rs

@@ -0,0 +1,75 @@
+use std::{fmt::Debug, sync::Arc};
+
+/// A snapshot of a single entry in the cache.
+///
+/// `Entry` is constructed from the methods like `or_insert` on the struct returned
+/// by cache's `entry` or `entry_by_ref` methods. `Entry` holds the cached key and
+/// value at the time it was constructed. It also carries extra information about the
+/// entry; [`is_fresh`](#method.is_fresh) method returns `true` if the value was not
+/// cached and was freshly computed.
+///
+/// See the followings for more information about `entry` and `entry_by_ref` methods:
+///
+/// - `sync::Cache`:
+///     - [`entry`](./sync/struct.Cache.html#method.entry)
+///     - [`entry_by_ref`](./sync/struct.Cache.html#method.entry_by_ref)
+/// - `future::Cache`:
+///     - [`entry`](./future/struct.Cache.html#method.entry)
+///     - [`entry_by_ref`](./future/struct.Cache.html#method.entry_by_ref)
+///
+pub struct Entry<K, V> {
+    key: Option<Arc<K>>,
+    value: V,
+    is_fresh: bool,
+}
+
+impl<K, V> Debug for Entry<K, V>
+where
+    K: Debug,
+    V: Debug,
+{
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Entry")
+            .field("key", self.key())
+            .field("value", &self.value)
+            .field("is_fresh", &self.is_fresh)
+            .finish()
+    }
+}
+
+impl<K, V> Entry<K, V> {
+    pub(crate) fn new(key: Option<Arc<K>>, value: V, is_fresh: bool) -> Self {
+        Self {
+            key,
+            value,
+            is_fresh,
+        }
+    }
+
+    /// Returns a reference to the wrapped key.
+    pub fn key(&self) -> &K {
+        self.key.as_ref().expect("Bug: Key is None")
+    }
+
+    /// Returns a reference to the wrapped value.
+    ///
+    /// Note that the returned reference is _not_ pointing to the original value in
+    /// the cache. Instead, it is pointing to the cloned value in this `Entry`.
+    pub fn value(&self) -> &V {
+        &self.value
+    }
+
+    /// Consumes this `Entry`, returning the wrapped value.
+    ///
+    /// Note that the returned value is a clone of the original value in the cache.
+    /// It was cloned when this `Entry` was constructed.
+    pub fn into_value(self) -> V {
+        self.value
+    }
+
+    /// Returns `true` if the value in this `Entry` was not cached and was freshly
+    /// computed.
+    pub fn is_fresh(&self) -> bool {
+        self.is_fresh
+    }
+}

src/future.rs

@@ -7,11 +7,13 @@ use std::{hash::Hash, sync::Arc};
 
 mod builder;
 mod cache;
+mod entry_selector;
 mod value_initializer;
 
 pub use {
     builder::CacheBuilder,
     cache::{BlockingOp, Cache},
+    entry_selector::{OwnedKeyEntrySelector, RefKeyEntrySelector},
 };
 
 /// The type of the unique ID to identify a predicate used by