Add entry/entry_async API for atomic cache access

- Add `entry()` / `entry_async()` with `FnOnce(&Key, &mut Val) -> EntryAction<T>`
  for atomic inspect-and-act under a write lock
- `EntryAction<T>`: `Retain(T)`, `Remove`, `ReplaceWithGuard`
- `EntryResult<T>`: `Retained(T)`, `Removed(K, V)`, `Replaced(Guard, V)`, `Vacant(Guard)`, `Timeout`
- Placeholder deduplication: concurrent callers wait (blocking or async) and retry
- Panic-safe weight accounting via `WeightGuard` drop guard
- Shuttle concurrency tests and docs/README updates

Closes #73, closes #77

Author: arthurprs

.github/workflows/ci.yml

@@ -106,7 +106,7 @@ jobs:
           command: clippy
           args: -- -D warnings
       - name: Install dependencies for tools
-        run: sudo apt-get -y install libfontconfig1-dev jq
+        run: sudo apt-get -y install libfontconfig1-dev jq --fix-missing
       - name: Check tools
         working-directory: tools
         run: cargo clippy -- -D warnings

README.md

@@ -12,6 +12,7 @@ Lightweight and high performance concurrent cache optimized for low cache overhe
 * Scales well with the number of threads
 * Atomic operations with `get_or_insert` and `get_value_or_guard` functions
 * Atomic async operations with `get_or_insert_async` and `get_value_or_guard_async` functions
+* Closure-based `entry` API for atomic inspect-and-act patterns (keep, remove, replace)
 * Supports item pinning
 * Iteration and draining
 * Handles zero weight items efficiently
@@ -50,7 +51,7 @@ struct StringWeighter;
 
 impl Weighter<u64, String> for StringWeighter {
     fn weight(&self, _key: &u64, val: &String) -> u64 {
-        // Be cautions out about zero weights!
+        // Be cautious about zero weights!
         val.len() as u64
     }
 }
@@ -64,6 +65,39 @@ fn main() {
 }
 ```
 
+Atomic inspect-and-act with the `entry` API
+
+```rust
+use quick_cache::sync::{Cache, EntryAction, EntryResult};
+
+fn main() {
+    let cache: Cache<u64, u64> = Cache::new(100);
+
+    // Insert-or-get: if absent, compute and insert; if present, return cached
+    let result = cache.entry(&0, None, |_key, val| EntryAction::Retain(*val));
+    let value = match result {
+        EntryResult::Retained(v) => v,
+        EntryResult::Vacant(guard) => {
+            let v = 42; // expensive computation
+            guard.insert(v).unwrap();
+            v
+        }
+        _ => unreachable!(),
+    };
+    assert_eq!(value, 42);
+
+    // Conditionally remove: evict entries below a threshold
+    let result = cache.entry(&0, None, |_key, val| {
+        if *val < 100 {
+            EntryAction::<()>::Remove
+        } else {
+            EntryAction::Retain(())
+        }
+    });
+    assert!(matches!(result, EntryResult::Removed(0, 42)));
+}
+```
+
 Using the `Equivalent` trait for complex keys
 
 ```rust

src/lib.rs

@@ -17,8 +17,8 @@
 //! # Equivalent keys
 //!
 //! The cache uses the [`Equivalent`](https://docs.rs/equivalent/1.0.1/equivalent/trait.Equivalent.html) trait
-//! for gets/removals. It can helps work around the `Borrow` limitations.
-//! For example, if the cache key is a tuple `(K, Q)`, you wouldn't be access to access such keys without
+//! for gets/removals. It can help work around the `Borrow` limitations.
+//! For example, if the cache key is a tuple `(K, Q)`, you wouldn't be able to access such keys without
 //! building a `&(K, Q)` and thus potentially cloning `K` and/or `Q`.
 //!
 //! # User defined weight
@@ -31,6 +31,10 @@
 //! are available, they can be mix and matched) the user can coordinate the insertion of entries, so only
 //! one value is "computed" and inserted after a cache miss.
 //!
+//! The `entry` family of functions provide a closure-based API for atomically
+//! inspecting and acting on existing entries (keep, remove, or replace) while also coordinating
+//! insertion on cache misses.
+//!
 //! # Lifecycle hooks
 //!
 //! A user can optionally provide a custom [Lifecycle] implementation to hook into the lifecycle of cache entries.
@@ -114,7 +118,7 @@ pub type DefaultHashBuilder = std::collections::hash_map::RandomState;
 ///
 /// impl Weighter<u64, String> for StringWeighter {
 ///     fn weight(&self, _key: &u64, val: &String) -> u64 {
-///         // Be cautious out about zero weights!
+///         // Be cautious about zero weights!
 ///         val.len() as u64
 ///     }
 /// }

src/options.rs

@@ -122,7 +122,7 @@ impl OptionsBuilder {
         self
     }
 
-    /// Builds an `Option` struct which can be used in the `Cache::with_options` constructor.
+    /// Builds an `Options` struct which can be used in the `Cache::with_options` constructor.
     #[inline]
     pub fn build(&self) -> Result<Options, Error> {
         let shards = self.shards.unwrap_or_else(|| available_parallelism() * 4);