Add shard_index method

[fsdvh]

Overview

Exposes a shard_index method on the Cache struct, allowing callers to determine which internal shard a given key maps to.

Motivation

Users who want to observe key distribution or batch operations against the same shard currently have no way to do this without re-implementing the shard selection logic themselves.

Changes

• Add pub fn shard_index<Q: Hash + ?Sized>(&self, key: &Q) -> usize to Cache
• Extract private compute_shard_index(&self, hash: u64) helper to deduplicate the rotate+mask logic shared with shard_for
• The returned index is guaranteed to be in [0, num_shards())

Use cases

• Key distribution analysis — check that keys spread evenly across shards
• Partitioning — being able to partition keys by shard

Notes

• The shard mapping depends on the BuildHasher supplied at construction; two caches built with different hashers may map the same key to different shards.
• ?Sized bound allows calling with unsized types (str, [u8]) consistent with all other key-taking methods.

[arthurprs]

Thank you for the PR.

batch operations against the same shard

If applicable, can you share more detail about this use case? I wonder if it should be covered in more ways.

[Copilot]

Pull request overview

Exposes a new Cache::shard_index API in the sync cache implementation so callers can determine which internal shard a key maps to, while deduplicating shard-selection logic.

Changes:

• Added pub fn shard_index<Q: Hash + ?Sized>(&self, key: &Q) -> usize on Cache.
• Extracted compute_shard_index(&self, hash: u64) helper to share the rotate+mask logic with shard_for.

---

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

[fsdvh]

Thank you for the PR.

batch operations against the same shard

If applicable, can you share more detail about this use case? I wonder if it should be covered in more ways.

I have significant tail latency caused by the write workflow (insert/eviction). While backpressure is necessary, I want to do it selectively — respecting shard boundaries to maintain high overall throughput while protecting individual shards from overload.

By identifying which shard a key belongs to, I can track per-shard load independently and apply backpressure only where needed, leaving unaffected shards free to operate at full capacity.