Interface StatsCounter

public interface StatsCounter
Stats Counter SPI - Cache statistics counter interface 统计计数器 SPI - 缓存统计计数器接口

Provides interface for recording cache statistics.

提供记录缓存统计信息的接口。

Features | 主要功能:

  • Hit/Miss recording - 命中/未命中记录
  • Load time recording - 加载时间记录
  • Eviction recording - 淘汰记录
  • Statistics snapshot - 统计快照

Usage Examples | 使用示例:

StatsCounter counter = StatsCounter.concurrent();
counter.recordHits(1);
counter.recordMisses(1);
CacheStats stats = counter.snapshot();

Security | 安全性:

  • Thread-safe: Implementation dependent - 线程安全: 取决于实现
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-cache V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static StatsCounter
    concurrent()
    Create concurrent counter using LongAdder 创建使用 LongAdder 的并发计数器
    static StatsCounter
    disabled()
    Create disabled counter (no-op) 创建禁用的计数器（空操作）
    void
    recordEviction(int weight)
    Record eviction 记录淘汰
    void
    recordHits(int count)
    Record cache hits 记录缓存命中
    void
    recordLoadFailure(long loadTime)
    Record failed load 记录失败加载
    void
    recordLoadSuccess(long loadTime)
    Record successful load 记录成功加载
    void
    recordMisses(int count)
    Record cache misses 记录缓存未命中
    default void
    reset()
    Reset all statistics counters 重置所有统计计数器
    static StatsCounter
    sampling(double sampleRate)
    Create sampling counter for high-throughput scenarios 创建高吞吐量场景的采样计数器
    static StatsCounter
    samplingBalanced()
    Create sampling counter with balanced accuracy/performance (10% sampling) 创建准确性/性能平衡的采样计数器（10% 采样）
    static StatsCounter
    samplingHighThroughput()
    Create sampling counter optimized for very high throughput (1% sampling) 创建超高吞吐量优化的采样计数器（1% 采样）
    CacheStats
    snapshot()
    Get statistics snapshot 获取统计快照

  • Method Details

    • recordHits

      void recordHits(int count)
      Record cache hits 记录缓存命中
      Parameters:
      count - number of hits | 命中次数

    • recordMisses

      void recordMisses(int count)
      Record cache misses 记录缓存未命中
      Parameters:
      count - number of misses | 未命中次数

    • recordLoadSuccess

      void recordLoadSuccess(long loadTime)
      Record successful load 记录成功加载
      Parameters:
      loadTime - load time in nanoseconds | 加载时间（纳秒）

    • recordLoadFailure

      void recordLoadFailure(long loadTime)
      Record failed load 记录失败加载
      Parameters:
      loadTime - load time in nanoseconds | 加载时间（纳秒）

    • recordEviction

      void recordEviction(int weight)
      Record eviction 记录淘汰
      Parameters:
      weight - evicted entry weight | 被淘汰条目的权重

    • snapshot

      CacheStats snapshot()
      Get statistics snapshot 获取统计快照
      Returns:
      statistics snapshot | 统计快照

    • reset

      default void reset()
      Reset all statistics counters 重置所有统计计数器

      Clears all hit, miss, load, and eviction counters to zero.

      将所有命中、未命中、加载和淘汰计数器清零。

      Since:
      V2.0.3

    • disabled

      static StatsCounter disabled()
      Create disabled counter (no-op) 创建禁用的计数器（空操作）
      Returns:
      disabled counter | 禁用的计数器

    • concurrent

      static StatsCounter concurrent()
      Create concurrent counter using LongAdder 创建使用 LongAdder 的并发计数器
      Returns:
      concurrent counter | 并发计数器

    • sampling

      static StatsCounter sampling(double sampleRate)
      Create sampling counter for high-throughput scenarios 创建高吞吐量场景的采样计数器

      Uses probabilistic sampling to reduce overhead while maintaining statistical accuracy.

      使用概率采样来降低开销，同时保持统计准确性。

      Parameters:
      sampleRate - sampling rate (0.0 to 1.0), e.g., 0.1 for 10% sampling | 采样率
      Returns:
      sampling counter | 采样计数器

    • samplingHighThroughput

      static StatsCounter samplingHighThroughput()
      Create sampling counter optimized for very high throughput (1% sampling) 创建超高吞吐量优化的采样计数器（1% 采样）
      Returns:
      high-throughput sampling counter | 高吞吐量采样计数器

    • samplingBalanced

      static StatsCounter samplingBalanced()
      Create sampling counter with balanced accuracy/performance (10% sampling) 创建准确性/性能平衡的采样计数器（10% 采样）
      Returns:
      balanced sampling counter | 平衡采样计数器