Add non-blocking (`try_*`) cache methods by fsdvh · Pull Request #112 · arthurprs/quick-cache

fsdvh · 2026-04-12T10:16:15Z

Summary

Adds try_read / try_write to the internal RwLock wrapper, normalizing
WouldBlock to None and panicking on poison (matching the blocking variants' behavior).
Introduces a LockContention error type returned by all non-blocking operations
when the target shard lock cannot be acquired immediately.
Adds non-blocking counterparts for all major cache operations on Cache:
- try_contains_key — returns Result<bool, LockContention>
- try_get — returns Result<Option<Val>, LockContention>
- try_peek — returns Result<Option<Val>, LockContention>
- try_remove — returns Result<Option<(Key, Val)>, LockContention>
- try_insert / try_insert_with_lifecycle — returns Result<(), (Key, Val)> /
  Result<L::RequestState, (Key, Val)> (key+value returned on contention so the
  caller can retry or discard)
All read-path methods return Err(LockContention) on contention; write-path insert
methods return Err((key, val)) so the caller can retry or discard without losing data.

Test plan

Unit tests added for each try_* method covering: hit, miss, and contended-lock scenarios.
test_try_remove_contended verifies the entry is still present after a failed non-blocking remove.
test_try_insert_contended verifies the key+value is returned to the caller on failure.
Run cargo test — all tests pass.

fsdvh · 2026-04-12T11:04:48Z

Let me know what you think, @arthurprs. Thank you in advance!

arthurprs · 2026-04-12T17:01:23Z

Thanks for the PR. In general I like the additions 👍 Do you think there's a practical benefit putting them behind the feature flag?

Copilot

Pull request overview

Adds an opt-in non-blocking Cargo feature that exposes non-blocking cache operations, allowing callers to skip work when a shard lock is contended instead of blocking. This extends the existing synchronous cache API with contention-aware variants while keeping the default (blocking) behavior unchanged.

Changes:

Introduces a non-blocking feature flag in Cargo.toml.
Adds try_read / try_write to the internal RwLock wrapper (feature-gated).
Adds ContendedResult plus Cache::try_* methods that return Contended on lock contention rather than blocking.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
Cargo.toml	Adds the `non-blocking` feature flag.
src/rw_lock.rs	Implements non-blocking `try_read`/`try_write` on the lock wrapper under the new feature.
src/sync.rs	Introduces `ContendedResult` and new `Cache::try_*` non-blocking operations gated by the feature.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

fsdvh · 2026-04-12T20:06:44Z

Thanks for the PR. In general I like the additions 👍 Do you think there's a practical benefit putting them behind the feature flag?

Putting it under a feature flag for convenience, if you think it belongs in the default feature set, I have no objections. 😄

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-21T08:00:10Z

+    /// Attempts to acquire this `RwLock` with shared read access without blocking.
+    ///
+    /// Returns `Some(guard)` if the lock was acquired, or `None` if it is already
+    /// held by a writer.
+    #[inline]
+    pub fn try_read(&self) -> Option<RwLockReadGuard<'_, T>> {
+        #[cfg(feature = "parking_lot")]
+        {
+            self.0.try_read().map(RwLockReadGuard)
+        }
+        #[cfg(not(feature = "parking_lot"))]
+        {
+            match self.0.try_read() {
+                Ok(guard) => Some(RwLockReadGuard(guard)),
+                Err(std::sync::TryLockError::WouldBlock) => None,
+                Err(std::sync::TryLockError::Poisoned(err)) => panic!("{}", err),
+            }


The non-blocking lock APIs are documented/implemented here as panicking on poison, but when the crate is built with the shuttle feature it uses the RwLock wrapper in src/shim.rs, whose try_read/try_write currently convert all errors (including poisoning) into None. That means Cache::try_* can silently treat a poisoned lock as mere contention under shuttle. Align the shuttle implementation with these semantics (panic on poison, None only for WouldBlock) so behavior is consistent across feature sets.

@arthurprs I think this is a valid suggestion, but it's outside the scope of this PR, wdyt?

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fsdvh · 2026-04-22T15:57:44Z

@arthurprs, if this is merged, can you also cut a release?

arthurprs · 2026-04-22T21:56:10Z

Sorry, I've been unable to get to this. I'll cut a release after merged 👍 that may be during this weekend.

fsdvh added 2 commits April 12, 2026 12:13

Add non-blocking methods

fd68bd6

Do not leak lcs

9fa1a83

fsdvh marked this pull request as ready for review April 12, 2026 10:21

fsdvh added 4 commits April 12, 2026 12:42

Dedicated result

7c6420c

More

f2c814b

Simplify

844072d

Cleanup + some docs

8eb51f5

fsdvh added 2 commits April 12, 2026 13:27

Docs

354b745

Use a feature flag

3d8fdf9

fsdvh changed the title ~~Add non-blocking methods for sync cache~~ Add non-blocking cache methods (non-blocking feature) Apr 12, 2026

arthurprs requested a review from Copilot April 12, 2026 17:00

Copilot started reviewing on behalf of arthurprs April 12, 2026 17:00 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

Comment thread src/rw_lock.rs

Comment thread src/rw_lock.rs Outdated

Comment thread src/sync.rs

Comment thread Cargo.toml

fsdvh added 2 commits April 12, 2026 22:11

Posion lock

6eaaea0

Remove feature and more tests

8282733

fsdvh changed the title ~~Add non-blocking cache methods (non-blocking feature)~~ Add non-blocking cache methods Apr 13, 2026

fsdvh requested a review from Copilot April 18, 2026 11:48

Copilot started reviewing on behalf of fsdvh April 18, 2026 11:48 View session

Copilot AI reviewed Apr 18, 2026

View reviewed changes

Comment thread src/sync.rs Outdated

Comment thread src/sync.rs Outdated

Comment thread src/sync.rs Outdated

Comment thread src/rw_lock.rs

fsdvh and others added 2 commits April 18, 2026 13:57

Update src/sync.rs

f99d3e9

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Simplify signature

44a052a

fsdvh requested a review from Copilot April 19, 2026 10:10

Copilot started reviewing on behalf of fsdvh April 19, 2026 10:10 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

Comment thread src/sync.rs Outdated

Comment thread src/rw_lock.rs

Comment thread src/sync.rs

Simplify

69b7c64

fsdvh changed the title ~~Add non-blocking cache methods~~ Add non-blocking (try_*) cache methods Apr 20, 2026

clippy

b4012a6

More docs

5bd558d

fsdvh requested a review from Copilot April 20, 2026 12:44

Copilot started reviewing on behalf of fsdvh April 20, 2026 12:45 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Comment thread src/sync.rs Outdated

Comment thread src/sync.rs Outdated

Comment thread README.md Outdated

Comment thread src/sync.rs Outdated

fsdvh and others added 3 commits April 20, 2026 15:16

Update README.md

3b6bc31

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/sync.rs

ff7cfad

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

AI suggestions

a85cfb8

fsdvh requested a review from Copilot April 21, 2026 07:54

Copilot started reviewing on behalf of fsdvh April 21, 2026 07:55 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Update src/sync.rs

8eb667c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Conversation

fsdvh commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

fsdvh commented Apr 12, 2026

Uh oh!

arthurprs commented Apr 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fsdvh commented Apr 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

fsdvh Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

fsdvh commented Apr 22, 2026

Uh oh!

arthurprs commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fsdvh commented Apr 12, 2026 •

edited

Loading