Dedicated method with state as an input

[fsdvh]

Summary

Adds insert_with_state and try_insert_with_state — variants of the existing _with_lifecycle methods that accept a caller-owned &mut L::RequestState instead of creating one internally. The existing _with_lifecycle methods are refactored to delegate to these, eliminating duplicated shard-lookup and insert logic.

Motivation

The _with_lifecycle methods give callers control over when evicted items are dropped (outside the shard lock). However, they each create their own lifecycle request, so callers who need to batch multiple insertions under a single begin_request/end_request pair had no supported way to do so.

The new _with_state methods fill this gap:

let mut lcs = cache.lifecycle.begin_request();
cache.insert_with_state(key1, val1, &mut lcs);
cache.insert_with_state(key2, val2, &mut lcs);
cache.lifecycle.end_request(lcs); // all evictions dropped here, once

Changes

• New: insert_with_state(&self, key, value, lcs: &mut L::RequestState) — blocking insert into an existing lifecycle request.
• New: try_insert_with_state(&self, key, value, lcs: &mut L::RequestState) -> Result<(), (Key, Val)> — non-blocking variant; returns inputs on lock contention.
• Refactor: insert_with_lifecycle and try_insert_with_lifecycle now delegate to the new methods.
• Docs: Improved doc comments for with_weighter, replace_with_lifecycle, insert_with_lifecycle, get_or_insert_with, and get_or_insert_async.

[arthurprs]

This is a good point and highlights that the API is limited. I'm leaning towards changing the lifecycles APIs to take &mut as you have here (See #124). That's a breaking change but justified.

[fsdvh]

This is a good point and highlights that the API is limited. I'm leaning towards changing the lifecycles APIs to take &mut as you have here (See #124). That's a breaking change but justified.

I really like your proposed changes. Happy to close my PR in favour of yours!

[fsdvh]

Closing in favour of #124