Interface StatsCounter

All Known Implementing Classes:
ConcurrentStatsCounter, DisabledStatsCounter, GuardedStatsCounter

public interface StatsCounter
Accumulates statistics during the operation of a Cache for presentation by Cache.stats(). This is solely intended for consumption by Cache implementors.
  • Method Summary

    Modifier and Type
    Method
    Description
    static @NonNull StatsCounter
    Returns an accumulator that does not record any cache events.
    static @NonNull StatsCounter
    guardedStatsCounter(@NonNull StatsCounter statsCounter)
    Returns an accumulator that suppresses and logs any exception thrown by the delegate statsCounter.
    void
    Deprecated.
    default void
    recordEviction(@org.checkerframework.checker.index.qual.NonNegative int weight)
    Deprecated.
    default void
    recordEviction(@org.checkerframework.checker.index.qual.NonNegative int weight, RemovalCause cause)
    Records the eviction of an entry from the cache.
    void
    recordHits(@org.checkerframework.checker.index.qual.NonNegative int count)
    Records cache hits.
    void
    recordLoadFailure(@org.checkerframework.checker.index.qual.NonNegative long loadTime)
    Records the failed load of a new entry.
    void
    recordLoadSuccess(@org.checkerframework.checker.index.qual.NonNegative long loadTime)
    Records the successful load of a new entry.
    void
    recordMisses(@org.checkerframework.checker.index.qual.NonNegative int count)
    Records cache misses.
    @NonNull CacheStats
    Returns a snapshot of this counter's values.
  • Method Details

    • recordHits

      void recordHits(@org.checkerframework.checker.index.qual.NonNegative int count)
      Records cache hits. This should be called when a cache request returns a cached value.
      Parameters:
      count - the number of hits to record
    • recordMisses

      void recordMisses(@org.checkerframework.checker.index.qual.NonNegative int count)
      Records cache misses. This should be called when a cache request returns a value that was not found in the cache. This method should be called by the loading thread, as well as by threads blocking on the load. Multiple concurrent calls to Cache lookup methods with the same key on an absent value should result in a single call to either recordLoadSuccess or recordLoadFailure and multiple calls to this method, despite all being served by the results of a single load operation.
      Parameters:
      count - the number of misses to record
    • recordLoadSuccess

      void recordLoadSuccess(@org.checkerframework.checker.index.qual.NonNegative long loadTime)
      Records the successful load of a new entry. This method should be called when a cache request causes an entry to be loaded (such as by Cache.get(K, java.util.function.Function<? super K, ? extends V>) or Map.computeIfAbsent(K, java.util.function.Function<? super K, ? extends V>)) and the loading completes successfully. In contrast to recordMisses(int), this method should only be called by the loading thread.
      Parameters:
      loadTime - the number of nanoseconds the cache spent computing or retrieving the new value
    • recordLoadFailure

      void recordLoadFailure(@org.checkerframework.checker.index.qual.NonNegative long loadTime)
      Records the failed load of a new entry. This method should be called when a cache request causes an entry to be loaded (such as by Cache.get(K, java.util.function.Function<? super K, ? extends V>) or Map.computeIfAbsent(K, java.util.function.Function<? super K, ? extends V>)), but an exception is thrown while loading the entry or the loading function returns null. In contrast to recordMisses(int), this method should only be called by the loading thread.
      Parameters:
      loadTime - the number of nanoseconds the cache spent computing or retrieving the new value prior to discovering the value doesn't exist or an exception being thrown
    • recordEviction

      @Deprecated void recordEviction()
      Deprecated.
      Use recordEviction(int, RemovalCause) instead. This method is scheduled for removal in version 3.0.0.
      Records the eviction of an entry from the cache. This should only been called when an entry is evicted due to the cache's eviction strategy, and not as a result of manual invalidations.
    • recordEviction

      @Deprecated default void recordEviction(@org.checkerframework.checker.index.qual.NonNegative int weight)
      Deprecated.
      Use recordEviction(int, RemovalCause) instead. This method is scheduled for removal in version 3.0.0.
      Records the eviction of an entry from the cache. This should only been called when an entry is evicted due to the cache's eviction strategy, and not as a result of manual invalidations.
      Parameters:
      weight - the weight of the evicted entry
    • recordEviction

      default void recordEviction(@org.checkerframework.checker.index.qual.NonNegative int weight, RemovalCause cause)
      Records the eviction of an entry from the cache. This should only been called when an entry is evicted due to the cache's eviction strategy, and not as a result of manual invalidations.
      Parameters:
      weight - the weight of the evicted entry
      cause - the reason for which the entry was removed
    • snapshot

      @NonNull CacheStats snapshot()
      Returns a snapshot of this counter's values. Note that this may be an inconsistent view, as it may be interleaved with update operations.

      Note: the values of the metrics are undefined in case of overflow (though it is guaranteed not to throw an exception). If you require specific handling, we recommend implementing your own stats collector.

      Returns:
      a snapshot of this counter's values
    • disabledStatsCounter

      static @NonNull StatsCounter disabledStatsCounter()
      Returns an accumulator that does not record any cache events.
      Returns:
      an accumulator that does not record metrics
    • guardedStatsCounter

      static @NonNull StatsCounter guardedStatsCounter(@NonNull StatsCounter statsCounter)
      Returns an accumulator that suppresses and logs any exception thrown by the delegate statsCounter.
      Parameters:
      statsCounter - the accumulator to delegate to
      Returns:
      an accumulator that suppresses and logs any exception thrown by the delegate