feat: use equivalent to loose the key trait bounds

.github/workflows/ci.yml

@@ -193,6 +193,7 @@ jobs:
           cargo llvm-cov --no-report run --example event_listener
           cargo llvm-cov --no-report run --features "tracing,jaeger" --example tail_based_tracing
           cargo llvm-cov --no-report run --features "tracing,ot" --example tail_based_tracing
+          cargo llvm-cov --no-report run --example equivalent
       - name: Run foyer-bench with coverage
         if: runner.os == 'Linux'
         env:

Cargo.toml

@@ -24,6 +24,20 @@ license = "Apache-2.0"
 readme = "README.md"
 
 [workspace.dependencies]
+bytesize = { package = "foyer-bytesize", version = "2" }
+clap = { version = "4", features = ["derive"] }
+equivalent = "1"
+fastrace = "0.7"
+fastrace-jaeger = "0.7"
+fastrace-opentelemetry = "0.7"
+hashbrown = "0.14"
+itertools = "0.13"
+metrics = "0.23"
+serde = { version = "1", features = ["derive", "rc"] }
+test-log = { version = "0.2", default-features = false, features = [
+    "trace",
+    "color",
+] }
 tokio = { package = "madsim-tokio", version = "0.2", features = [
     "rt",
     "rt-multi-thread",
@@ -33,19 +47,7 @@ tokio = { package = "madsim-tokio", version = "0.2", features = [
     "signal",
     "fs",
 ] }
-serde = { version = "1", features = ["derive", "rc"] }
-test-log = { version = "0.2", default-features = false, features = [
-    "trace",
-    "color",
-] }
-itertools = "0.13"
-metrics = "0.23"
-fastrace = "0.7"
-fastrace-jaeger = "0.7"
-fastrace-opentelemetry = "0.7"
-clap = { version = "4", features = ["derive"] }
-bytesize = { package = "foyer-bytesize", version = "2" }
-hashbrown = "0.14"
+
 # foyer components
 foyer-common = { version = "0.12.2", path = "foyer-common" }
 foyer-intrusive = { version = "0.12.2", path = "foyer-intrusive" }

Makefile

@@ -43,6 +43,7 @@ example:
 	cargo run --example event_listener
 	cargo run --features "tracing,jaeger" --example tail_based_tracing
 	cargo run --features "tracing,ot" --example tail_based_tracing
+	cargo run --example equivalent
 
 full: check-all test-all example udeps
 

examples/Cargo.toml

@@ -17,6 +17,7 @@ publish = false
 ahash = "0.8"
 anyhow = "1"
 chrono = "0.4"
+equivalent = { workspace = true }
 fastrace = { workspace = true }
 fastrace-jaeger = { workspace = true, optional = true }
 fastrace-opentelemetry = { workspace = true, optional = true }
@@ -60,3 +61,7 @@ path = "event_listener.rs"
 [[example]]
 name = "tail_based_tracing"
 path = "tail_based_tracing.rs"
+
+[[example]]
+name = "equivalent"
+path = "equivalent.rs"

examples/equivalent.rs

@@ -0,0 +1,43 @@
+//  Copyright 2024 foyer Project Authors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+use equivalent::Equivalent;
+use foyer::{Cache, CacheBuilder};
+
+#[derive(Hash, PartialEq, Eq)]
+pub struct Pair<A, B>(pub A, pub B);
+
+// FYI: https://docs.rs/equivalent
+impl<'a, A: ?Sized, B: ?Sized, C, D> Equivalent<(C, D)> for Pair<&'a A, &'a B>
+where
+    A: Equivalent<C>,
+    B: Equivalent<D>,
+{
+    fn equivalent(&self, key: &(C, D)) -> bool {
+        self.0.equivalent(&key.0) && self.1.equivalent(&key.1)
+    }
+}
+
+fn main() {
+    let cache: Cache<(String, String), String> = CacheBuilder::new(16).build();
+
+    let entry = cache.insert(
+        ("hello".to_string(), "world".to_string()),
+        "This is a string tuple pair.".to_string(),
+    );
+    // With `Equivalent`, `Pair(&str, &str)` can be used to compared `(String, String)`!
+    let e = cache.get(&Pair("hello", "world")).unwrap();
+
+    assert_eq!(entry.value(), e.value());
+}

foyer-common/src/code.rs

@@ -17,7 +17,7 @@ use std::hash::{BuildHasher, Hash};
 use serde::{de::DeserializeOwned, Serialize};
 
 /// Key trait for the in-memory cache.
-pub trait Key: Send + Sync + 'static + Hash + Eq + PartialEq {}
+pub trait Key: Send + Sync + 'static + Hash + Eq {}
 /// Value trait for the in-memory cache.
 pub trait Value: Send + Sync + 'static {}
 

foyer-memory/Cargo.toml

@@ -16,6 +16,7 @@ readme = { workspace = true }
 ahash = "0.8"
 bitflags = "2"
 cmsketch = "0.2.1"
+equivalent = { workspace = true }
 fastrace = { workspace = true }
 foyer-common = { workspace = true }
 foyer-intrusive = { workspace = true }

foyer-memory/src/cache.rs

@@ -12,9 +12,10 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-use std::{borrow::Borrow, fmt::Debug, hash::Hash, ops::Deref, sync::Arc};
+use std::{fmt::Debug, hash::Hash, ops::Deref, sync::Arc};
 
 use ahash::RandomState;
+use equivalent::Equivalent;
 use foyer_common::{
     code::{HashBuilder, Key, Value},
     event::EventListener,
@@ -566,8 +567,7 @@ where
     #[fastrace::trace(name = "foyer::memory::cache::remove")]
     pub fn remove<Q>(&self, key: &Q) -> Option<CacheEntry<K, V, S>>
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         match self {
             Cache::Fifo(cache) => cache.remove(key).map(CacheEntry::from),
@@ -581,8 +581,7 @@ where
     #[fastrace::trace(name = "foyer::memory::cache::get")]
     pub fn get<Q>(&self, key: &Q) -> Option<CacheEntry<K, V, S>>
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         match self {
             Cache::Fifo(cache) => cache.get(key).map(CacheEntry::from),
@@ -596,8 +595,7 @@ where
     #[fastrace::trace(name = "foyer::memory::cache::contains")]
     pub fn contains<Q>(&self, key: &Q) -> bool
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         match self {
             Cache::Fifo(cache) => cache.contains(key),
@@ -613,8 +611,7 @@ where
     #[fastrace::trace(name = "foyer::memory::cache::touch")]
     pub fn touch<Q>(&self, key: &Q) -> bool
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         match self {
             Cache::Fifo(cache) => cache.touch(key),
@@ -658,7 +655,6 @@ where
     /// Hash the given key with the hash builder of the cache.
     pub fn hash<Q>(&self, key: &Q) -> u64
     where
-        K: Borrow<Q>,
         Q: Hash + ?Sized,
     {
         self.hash_builder().hash_one(key)

foyer-memory/src/generic.rs

@@ -13,7 +13,6 @@
 //  limitations under the License.
 
 use std::{
-    borrow::Borrow,
     fmt::Debug,
     future::Future,
     hash::Hash,
@@ -28,6 +27,7 @@
 };
 
 use ahash::RandomState;
+use equivalent::Equivalent;
 use fastrace::{future::InSpan, prelude::*};
 use foyer_common::{
     code::{HashBuilder, Key, Value},
@@ -171,8 +171,7 @@
 
     unsafe fn get<Q>(&mut self, hash: u64, key: &Q) -> Option<NonNull<E::Handle>>
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let mut ptr = match self.indexer.get(hash, key) {
             Some(ptr) => {
@@ -196,16 +195,14 @@
 
     unsafe fn contains<Q>(&mut self, hash: u64, key: &Q) -> bool
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         self.indexer.get(hash, key).is_some()
     }
 
     unsafe fn touch<Q>(&mut self, hash: u64, key: &Q) -> bool
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let res = self.indexer.get(hash, key);
         if let Some(ptr) = res {
@@ -219,8 +216,7 @@
     /// Return `Some(..)` if the handle is released, or `None` if the handle is still in use.
     unsafe fn remove<Q>(&mut self, hash: u64, key: &Q) -> Option<NonNull<E::Handle>>
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let mut ptr = self.indexer.remove(hash, key)?;
         let handle = ptr.as_mut();
@@ -608,8 +604,7 @@
     #[fastrace::trace(name = "foyer::memory::generic::remove")]
     pub fn remove<Q>(self: &Arc<Self>, key: &Q) -> Option<GenericCacheEntry<K, V, E, I, S>>
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let hash = self.hash_builder.hash_one(key);
 
@@ -625,8 +620,7 @@
     #[fastrace::trace(name = "foyer::memory::generic::get")]
     pub fn get<Q>(self: &Arc<Self>, key: &Q) -> Option<GenericCacheEntry<K, V, E, I, S>>
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let hash = self.hash_builder.hash_one(key);
 
@@ -641,8 +635,7 @@
 
     pub fn contains<Q>(self: &Arc<Self>, key: &Q) -> bool
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let hash = self.hash_builder.hash_one(key);
 
@@ -654,8 +647,7 @@
 
     pub fn touch<Q>(&self, key: &Q) -> bool
     where
-        K: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<K> + ?Sized,
     {
         let hash = self.hash_builder.hash_one(key);
 

foyer-memory/src/indexer/hash_table.rs

@@ -12,8 +12,9 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-use std::{borrow::Borrow, hash::Hash, ptr::NonNull};
+use std::{hash::Hash, ptr::NonNull};
 
+use equivalent::Equivalent;
 use foyer_common::{code::Key, strict_assert};
 use hashbrown::hash_table::{Entry as HashTableEntry, HashTable};
 
@@ -83,20 +84,18 @@ where
 
     unsafe fn get<Q>(&self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<Self::Key> + ?Sized,
     {
-        self.table.find(hash, |p| p.as_ref().key().borrow() == key).copied()
+        self.table.find(hash, |p| key.equivalent(p.as_ref().key())).copied()
     }
 
     unsafe fn remove<Q>(&mut self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: Borrow<Q>,
-        Q: Hash + Eq + ?Sized,
+        Q: Hash + Equivalent<Self::Key> + ?Sized,
     {
         match self
             .table
-            .entry(hash, |p| p.as_ref().key().borrow() == key, |p| p.as_ref().base().hash())
+            .entry(hash, |p| key.equivalent(p.as_ref().key()), |p| p.as_ref().base().hash())
         {
             HashTableEntry::Occupied(o) => {
                 let (mut p, _) = o.remove();

foyer-memory/src/indexer/mod.rs

@@ -12,8 +12,9 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-use std::{borrow::Borrow, hash::Hash, ptr::NonNull};
+use std::{hash::Hash, ptr::NonNull};
 
+use equivalent::Equivalent;
 use foyer_common::code::Key;
 
 use crate::handle::KeyedHandle;
@@ -26,12 +27,10 @@ pub trait Indexer: Send + Sync + 'static {
     unsafe fn insert(&mut self, ptr: NonNull<Self::Handle>) -> Option<NonNull<Self::Handle>>;
     unsafe fn get<Q>(&self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: Borrow<Q>,
-        Q: Hash + Eq + ?Sized;
+        Q: Hash + Equivalent<Self::Key> + ?Sized;
     unsafe fn remove<Q>(&mut self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: Borrow<Q>,
-        Q: Hash + Eq + ?Sized;
+        Q: Hash + Equivalent<Self::Key> + ?Sized;
     unsafe fn drain(&mut self) -> impl Iterator<Item = NonNull<Self::Handle>>;
 }
 

foyer-memory/src/indexer/sanity.rs

@@ -14,6 +14,8 @@
 
 use std::ptr::NonNull;
 
+use equivalent::Equivalent;
+
 use super::Indexer;
 #[cfg(feature = "sanity")]
 use crate::handle::Handle;
@@ -49,8 +51,7 @@ where
 
     unsafe fn get<Q>(&self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: std::borrow::Borrow<Q>,
-        Q: std::hash::Hash + Eq + ?Sized,
+        Q: std::hash::Hash + Equivalent<Self::Key> + ?Sized,
     {
         self.indexer
             .get(hash, key)
@@ -59,8 +60,7 @@ where
 
     unsafe fn remove<Q>(&mut self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: std::borrow::Borrow<Q>,
-        Q: std::hash::Hash + Eq + ?Sized,
+        Q: std::hash::Hash + Equivalent<Self::Key> + ?Sized,
     {
         self.indexer
             .remove(hash, key)
@@ -90,16 +90,14 @@ where
 
     unsafe fn get<Q>(&self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: std::borrow::Borrow<Q>,
-        Q: std::hash::Hash + Eq + ?Sized,
+        Q: std::hash::Hash + Equivalent<Self::Key> + ?Sized,
     {
         self.indexer.get(hash, key)
     }
 
     unsafe fn remove<Q>(&mut self, hash: u64, key: &Q) -> Option<NonNull<Self::Handle>>
     where
-        Self::Key: std::borrow::Borrow<Q>,
-        Q: std::hash::Hash + Eq + ?Sized,
+        Q: std::hash::Hash + Equivalent<Self::Key> + ?Sized,
     {
         self.indexer.remove(hash, key)
     }