Add non-blocking cache methods (non-blocking feature)

[fsdvh]

Adds opt-in, non-blocking variants of the core cache operations via a new non-blocking Cargo feature.

Motivation

Under high write contention a caller may prefer to skip a cache operation rather than block waiting for a shard lock. The existing API offers no way to express this — every operation blocks until the lock is acquired.

Changes

Cargo.toml

• New non-blocking = [] feature flag (off by default).

src/rw_lock.rs

• Added try_read / try_write on the internal RwLock wrapper, gated on #[cfg(feature = "non-blocking")].
• Normalises the return type to Option<Guard> across all three backing implementations (parking_lot, crossbeam ShardedLock, std::sync).

src/sync.rs

• New ContendedResult<Val> enum with variants Ok(Val) and Contended, plus ok() / is_contended() helpers.
• Six new methods on Cache, each returning ContendedResult and falling back to Contended instead of blocking:
  • try_contains_key
  • try_get
  • try_peek
  • try_remove
  • try_insert
  • try_insert_with_lifecycle

Usage

quick_cache = { version = "...", features = ["non-blocking"] }

match cache.try_get(&key) {
    ContendedResult::Ok(Some(val)) => { /* cache hit */ }
    ContendedResult::Ok(None)      => { /* cache miss */ }
    ContendedResult::Contended     => { /* shard was locked, skip or fall back */ }
}

[fsdvh]

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

[arthurprs]

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.

[Copilot]

try_read() maps any Err from the non-parking_lot backends to None via .ok(), which silently treats a poisoned lock the same as contention. This changes behavior vs read() (which panics on poisoning) and also makes the docs inaccurate (poisoning isn't “held by a writer”). Consider matching on TryLockError and only returning None for WouldBlock, while panicking (or otherwise explicitly handling) Poisoned to keep semantics consistent.

[Copilot]

New non-blocking APIs (try_contains_key/try_get/try_peek/try_remove/try_insert*) add important behavior (returning Contended instead of blocking) but there are no feature-gated tests exercising the contended path. Add #[cfg(feature = "non-blocking")] unit tests that hold a shard read/write lock (tests can use the private shard_for helper) and assert these methods return Contended without blocking, plus a basic success-path assertion.

[Copilot]

The new non-blocking feature gates public API items, but docs.rs is configured to build docs with only features = ["stats"]. That means the new ContendedResult and Cache::try_* methods won’t appear in published docs by default. Consider adding non-blocking to package.metadata.docs.rs.features (or documenting that users must enable it locally) so the new API is discoverable.

[fsdvh]

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. 😄