CacheStats
Date: 2016-05-24

com.google.common.cache

## Class CacheStats

- java.lang.Object
- - com.google.common.cache.CacheStats

-     @GwtCompatible
      public final class CacheStats
      extends java.lang.Object

  Statistics about the performance of a `Cache`. Instances of this class are immutable.

  Cache statistics are incremented according to the following rules:

  - When a cache lookup encounters an existing cache entry `hitCount` is incremented.
  - When a cache lookup first encounters a missing cache entry, a new entry is loaded.
    - After successfully loading an entry `missCount` and `loadSuccessCount` are incremented, and the total loading time, in nanoseconds, is added to `totalLoadTime`.
    - When an exception is thrown while loading an entry, `missCount` and `loadExceptionCount` are incremented, and the total loading time, in nanoseconds, is added to `totalLoadTime`.
    - Cache lookups that encounter a missing cache entry that is still loading will wait for loading to complete (whether successful or not) and then increment `missCount`.
  - When an entry is evicted from the cache, `evictionCount` is incremented.
  - No stats are modified when a cache entry is invalidated or manually removed.
  - No stats are modified by operations invoked on the asMap view of the cache.

  A lookup is specifically defined as an invocation of one of the methods `LoadingCache.get(Object)`, `LoadingCache.getUnchecked(Object)`, `Cache.get(Object, Callable)`, or `LoadingCache.getAll(Iterable)`.

  Since:
    10.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CacheStats(long hitCount, long missCount, long loadSuccessCount, long loadExceptionCount, long totalLoadTime, long evictionCount)` Constructs a new `CacheStats` instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `averageLoadPenalty()` Returns the average time spent loading new values.
    `boolean` | `equals(java.lang.Object object)`
    `long` | `evictionCount()` Returns the number of times an entry has been evicted.
    `int` | `hashCode()`
    `long` | `hitCount()` Returns the number of times `Cache` lookup methods have returned a cached value.
    `double` | `hitRate()` Returns the ratio of cache requests which were hits.
    `long` | `loadCount()` Returns the total number of times that `Cache` lookup methods attempted to load new values.
    `long` | `loadExceptionCount()` Returns the number of times `Cache` lookup methods threw an exception while loading a new value.
    `double` | `loadExceptionRate()` Returns the ratio of cache loading attempts which threw exceptions.
    `long` | `loadSuccessCount()` Returns the number of times `Cache` lookup methods have successfully loaded a new value.
    `CacheStats` | `minus(CacheStats other)` Returns a new `CacheStats` representing the difference between this `CacheStats` and `other`.
    `long` | `missCount()` Returns the number of times `Cache` lookup methods have returned an uncached (newly loaded) value, or null.
    `double` | `missRate()` Returns the ratio of cache requests which were misses.
    `CacheStats` | `plus(CacheStats other)` Returns a new `CacheStats` representing the sum of this `CacheStats` and `other`.
    `long` | `requestCount()` Returns the number of times `Cache` lookup methods have returned either a cached or uncached value.
    `java.lang.String` | `toString()`
    `long` | `totalLoadTime()` Returns the total number of nanoseconds the cache has spent loading new values.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### CacheStats

          public CacheStats(long hitCount,
                    long missCount,
                    long loadSuccessCount,
                    long loadExceptionCount,
                    long totalLoadTime,
                    long evictionCount)

      Constructs a new `CacheStats` instance.

      Five parameters of the same type in a row is a bad thing, but this class is not constructed by end users and is too fine-grained for a builder.

  - ### Method Detail

    - #### requestCount

          public long requestCount()

      Returns the number of times `Cache` lookup methods have returned either a cached or uncached value. This is defined as `hitCount + missCount`.

    - #### hitCount

          public long hitCount()

      Returns the number of times `Cache` lookup methods have returned a cached value.

    - #### hitRate

          public double hitRate()

      Returns the ratio of cache requests which were hits. This is defined as `hitCount / requestCount`, or `1.0` when `requestCount == 0`. Note that `hitRate + missRate =~ 1.0`.

    - #### missCount

          public long missCount()

      Returns the number of times `Cache` lookup methods have returned an uncached (newly loaded) value, or null. Multiple concurrent calls to `Cache` lookup methods on an absent value can result in multiple misses, all returning the results of a single cache load operation.

    - #### missRate

          public double missRate()

      Returns the ratio of cache requests which were misses. This is defined as `missCount / requestCount`, or `0.0` when `requestCount == 0`. Note that `hitRate + missRate =~ 1.0`. Cache misses include all requests which weren't cache hits, including requests which resulted in either successful or failed loading attempts, and requests which waited for other threads to finish loading. It is thus the case that `missCount &gt;= loadSuccessCount + loadExceptionCount`. Multiple concurrent misses for the same key will result in a single load operation.

    - #### loadCount

          public long loadCount()

      Returns the total number of times that `Cache` lookup methods attempted to load new values. This includes both successful load operations, as well as those that threw exceptions. This is defined as `loadSuccessCount + loadExceptionCount`.

    - #### loadSuccessCount

          public long loadSuccessCount()

      Returns the number of times `Cache` lookup methods have successfully loaded a new value. This is always incremented in conjunction with `missCount`, though `missCount` is also incremented when an exception is encountered during cache loading (see `loadExceptionCount`). Multiple concurrent misses for the same key will result in a single load operation.

    - #### loadExceptionCount

          public long loadExceptionCount()

      Returns the number of times `Cache` lookup methods threw an exception while loading a new value. This is always incremented in conjunction with `missCount`, though `missCount` is also incremented when cache loading completes successfully (see `loadSuccessCount`). Multiple concurrent misses for the same key will result in a single load operation.

    - #### loadExceptionRate

          public double loadExceptionRate()

      Returns the ratio of cache loading attempts which threw exceptions. This is defined as `loadExceptionCount / (loadSuccessCount + loadExceptionCount)`, or `0.0` when `loadSuccessCount + loadExceptionCount == 0`.

    - #### totalLoadTime

          public long totalLoadTime()

      Returns the total number of nanoseconds the cache has spent loading new values. This can be used to calculate the miss penalty. This value is increased every time `loadSuccessCount` or `loadExceptionCount` is incremented.

    - #### averageLoadPenalty

          public double averageLoadPenalty()

      Returns the average time spent loading new values. This is defined as `totalLoadTime / (loadSuccessCount + loadExceptionCount)`.

    - #### evictionCount

          public long evictionCount()

      Returns the number of times an entry has been evicted. This count does not include manual invalidations.

    - #### minus

          public CacheStats minus(CacheStats other)

      Returns a new `CacheStats` representing the difference between this `CacheStats` and `other`. Negative values, which aren't supported by `CacheStats` will be rounded up to zero.

    - #### plus

          public CacheStats plus(CacheStats other)

      Returns a new `CacheStats` representing the sum of this `CacheStats` and `other`.
      Since:
        11.0

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object object)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`