Class CacheStats
- java.lang.Object
-
- com.google.common.cache.CacheStats
-
@GwtCompatible public final class CacheStats extends Object
Statistics about the performance of aCache
. 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
andloadSuccessCount
are incremented, and the total loading time, in nanoseconds, is added tototalLoadTime
. - When an exception is thrown while loading an entry,
missCount
andloadExceptionCount
are incremented, and the total loading time, in nanoseconds, is added tototalLoadTime
. - 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
.
- After successfully loading an entry
- 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)
, orLoadingCache.getAll(Iterable)
.- Since:
- 10.0
- Author:
- Charles Fry
- When a cache lookup encounters an existing cache entry
-
-
Constructor Summary
Constructors Constructor Description CacheStats(long hitCount, long missCount, long loadSuccessCount, long loadExceptionCount, long totalLoadTime, long evictionCount)
Constructs a newCacheStats
instance.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description double
averageLoadPenalty()
Returns the average time spent loading new values.boolean
equals(Object object)
Indicates whether some other object is "equal to" this one.long
evictionCount()
Returns the number of times an entry has been evicted.int
hashCode()
Returns a hash code value for the object.long
hitCount()
Returns the number of timesCache
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 thatCache
lookup methods attempted to load new values.long
loadExceptionCount()
Returns the number of timesCache
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 timesCache
lookup methods have successfully loaded a new value.CacheStats
minus(CacheStats other)
Returns a newCacheStats
representing the difference between thisCacheStats
andother
.long
missCount()
Returns the number of timesCache
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 newCacheStats
representing the sum of thisCacheStats
andother
.long
requestCount()
Returns the number of timesCache
lookup methods have returned either a cached or uncached value.String
toString()
Returns a string representation of the object.long
totalLoadTime()
Returns the total number of nanoseconds the cache has spent loading new values.
-
-
-
Constructor Detail
-
CacheStats
public CacheStats(long hitCount, long missCount, long loadSuccessCount, long loadExceptionCount, long totalLoadTime, long evictionCount)
Constructs a newCacheStats
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 timesCache
lookup methods have returned either a cached or uncached value. This is defined ashitCount + missCount
.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.
-
hitCount
public long hitCount()
Returns the number of timesCache
lookup methods have returned a cached value.
-
hitRate
public double hitRate()
Returns the ratio of cache requests which were hits. This is defined ashitCount / requestCount
, or1.0
whenrequestCount == 0
. Note thathitRate + missRate =~ 1.0
.
-
missCount
public long missCount()
-
missRate
public double missRate()
Returns the ratio of cache requests which were misses. This is defined asmissCount / requestCount
, or0.0
whenrequestCount == 0
. Note thathitRate + 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 thatmissCount >= 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 thatCache
lookup methods attempted to load new values. This includes both successful load operations, as well as those that threw exceptions. This is defined asloadSuccessCount + loadExceptionCount
.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.
-
loadSuccessCount
public long loadSuccessCount()
Returns the number of timesCache
lookup methods have successfully loaded a new value. This is usually incremented in conjunction withmissCount
, thoughmissCount
is also incremented when an exception is encountered during cache loading (seeloadExceptionCount
). Multiple concurrent misses for the same key will result in a single load operation. This may be incremented not in conjunction withmissCount
if the load occurs as a result of a refresh or if the cache loader returned more items than was requested.missCount
may also be incremented not in conjunction with this (norloadExceptionCount
) on calls togetIfPresent
.
-
loadExceptionCount
public long loadExceptionCount()
Returns the number of timesCache
lookup methods threw an exception while loading a new value. This is usually incremented in conjunction withmissCount
, thoughmissCount
is also incremented when cache loading completes successfully (seeloadSuccessCount
). Multiple concurrent misses for the same key will result in a single load operation. This may be incremented not in conjunction withmissCount
if the load occurs as a result of a refresh or if the cache loader returned more items than was requested.missCount
may also be incremented not in conjunction with this (norloadSuccessCount
) on calls togetIfPresent
.
-
loadExceptionRate
public double loadExceptionRate()
Returns the ratio of cache loading attempts which threw exceptions. This is defined asloadExceptionCount / (loadSuccessCount + loadExceptionCount)
, or0.0
whenloadSuccessCount + loadExceptionCount == 0
.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.
-
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 timeloadSuccessCount
orloadExceptionCount
is incremented.
-
averageLoadPenalty
public double averageLoadPenalty()
Returns the average time spent loading new values. This is defined astotalLoadTime / (loadSuccessCount + loadExceptionCount)
.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.
-
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 newCacheStats
representing the difference between thisCacheStats
andother
. Negative values, which aren't supported byCacheStats
will be rounded up to zero.
-
plus
public CacheStats plus(CacheStats other)
Returns a newCacheStats
representing the sum of thisCacheStats
andother
.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.
- Since:
- 11.0
-
hashCode
public int hashCode()
Description copied from class:java.lang.Object
Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided byHashMap
.The general contract of
hashCode
is:- Whenever it is invoked on the same object more than once during
an execution of a Java application, the
hashCode
method must consistently return the same integer, provided no information used inequals
comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. - If two objects are equal according to the
equals(Object)
method, then calling thehashCode
method on each of the two objects must produce the same integer result. - It is not required that if two objects are unequal
according to the
Object.equals(java.lang.Object)
method, then calling thehashCode
method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by class
Object
does return distinct integers for distinct objects. (The hashCode may or may not be implemented as some function of an object's memory address at some point in time.)- Overrides:
hashCode
in classObject
- Returns:
- a hash code value for this object.
- See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
- Whenever it is invoked on the same object more than once during
an execution of a Java application, the
-
equals
public boolean equals(@CheckForNull Object object)
Description copied from class:java.lang.Object
Indicates whether some other object is "equal to" this one.The
equals
method implements an equivalence relation on non-null object references:- It is reflexive: for any non-null reference value
x
,x.equals(x)
should returntrue
. - It is symmetric: for any non-null reference values
x
andy
,x.equals(y)
should returntrue
if and only ify.equals(x)
returnstrue
. - It is transitive: for any non-null reference values
x
,y
, andz
, ifx.equals(y)
returnstrue
andy.equals(z)
returnstrue
, thenx.equals(z)
should returntrue
. - It is consistent: for any non-null reference values
x
andy
, multiple invocations ofx.equals(y)
consistently returntrue
or consistently returnfalse
, provided no information used inequals
comparisons on the objects is modified. - For any non-null reference value
x
,x.equals(null)
should returnfalse
.
The
equals
method for classObject
implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference valuesx
andy
, this method returnstrue
if and only ifx
andy
refer to the same object (x == y
has the valuetrue
).Note that it is generally necessary to override the
hashCode
method whenever this method is overridden, so as to maintain the general contract for thehashCode
method, which states that equal objects must have equal hash codes.- Overrides:
equals
in classObject
- Parameters:
object
- the reference object with which to compare.- Returns:
true
if this object is the same as the obj argument;false
otherwise.- See Also:
Object.hashCode()
,HashMap
- It is reflexive: for any non-null reference value
-
toString
public String toString()
Description copied from class:java.lang.Object
Returns a string representation of the object. In general, thetoString
method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.The
toString
method for classObject
returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@
', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:getClass().getName() + '@' + Integer.toHexString(hashCode())
-
-