Skip to content

Add per-item access count stats (blocking and non-blocking)#128

Merged
arthurprs merged 16 commits into
arthurprs:masterfrom
fsdvh:expose-item-stats
Jun 26, 2026
Merged

Add per-item access count stats (blocking and non-blocking)#128
arthurprs merged 16 commits into
arthurprs:masterfrom
fsdvh:expose-item-stats

Conversation

@fsdvh

@fsdvh fsdvh commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Expose per-item access statistics behind the existing stats feature.

What

  • Adds a public ItemStats struct (currently exposing access_count) returned by a new item_stats method on the sync Cache, the unsync::Cache, and the internal CacheShard.
  • Adds a non-blocking try_item_stats on the sync Cache: it returns Ok(Some(stats)) / Ok(None) like item_stats, or Err(LockContention) if the shard lock could not be acquired without blocking — matching the other try_* methods.
  • access_count tracks how many times an item has been read (get/get_mut/get_value_or_guard/entry) since it became resident. Unlike the internal referenced eviction counter, it is monotonic per residency and not bounded by the eviction policy. It resets to zero when the slot is reused for a new value.
  • Both item_stats and try_item_stats behave like a peek: they do not affect the item's hotness or its access count, and return None when the key is not resident.

Notes

  • All new fields, methods, and the ItemStats type are gated behind #[cfg(feature = "stats")], so default builds are unaffected.
  • The per-item access_count adds an AtomicU64 to each Resident, so the entry_overhead size test is only asserted when the stats feature is disabled.

fsdvh and others added 10 commits April 13, 2026 10:39
Add non-blocking API for sync cache
Expose shard_index method
* Add non-blocking methods

* Do not leak lcs

* Dedicated result

* More

* Simplify

* Cleanup + some docs

* Docs

* Use a feature flag

* Posion lock

* Remove feature and more tests

* Update src/sync.rs

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

* Simplify signature

* Simplify

* clippy

* More docs

* Update README.md

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

* Update src/sync.rs

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

* AI suggestions

* Update src/sync.rs

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

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Dedicated method with state as an input

* Shared state methods

* More docs
@fsdvh fsdvh changed the title Add per-item stats Add per-item access count stats Jun 25, 2026
@arthurprs

Copy link
Copy Markdown
Owner

Good addition, thank you. I was almost considering removing the stats feature etc.., but this adds more value to it.

I may add a short commit to the PR before merging later this week.

@fsdvh

fsdvh commented Jun 25, 2026

Copy link
Copy Markdown
Contributor Author

Good addition, thank you. I was almost considering removing the stats feature etc.., but this adds more value to it.

I may add a short commit to the PR before merging later this week.

Thank you for your feedback. We're building a solution on top of quick-cache that introduces persistence, and having such per-item stats would be beneficial for decision-making during content prioritization.

@fsdvh fsdvh changed the title Add per-item access count stats Add per-item access count stats (blocking and non-blocking) Jun 26, 2026
fsdvh and others added 2 commits June 26, 2026 14:22
…s, document stats overhead

- Fold record_item_hit{,_mut} into arity-overloaded record_hit{,_mut}
  arms so each resident hit-site records both counters in one call.
- Re-enable entry_overhead under the stats feature; assert the real
  per-cache sizes (sync unchanged, unsync +8 via discriminant niche).
- Document the stats feature's per-entry size and per-hit/miss cost.
@arthurprs arthurprs merged commit 99809ce into arthurprs:master Jun 26, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants