Module com.github.benmanes.caffeine
Package com.github.benmanes.caffeine.cache

Interface Policy.Eviction<K,​V>

  • Enclosing interface:
    Policy<K,​V>
    public static interface Policy.Eviction<K,​V>
    The low-level operations for a cache with a size-based eviction policy.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      Map<K,​V> coldest​(@org.checkerframework.checker.index.qual.NonNegative int limit)
      Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
      default <T> T coldest​(Function<Stream<Policy.CacheEntry<K,​V>>,​T> mappingFunction)
      Returns the computed result from the ordered traversal of the cache entries.
      default Map<K,​V> coldestWeighted​(@org.checkerframework.checker.index.qual.NonNegative long weightLimit)
      Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
      @org.checkerframework.checker.index.qual.NonNegative long getMaximum()
      Returns the maximum total weighted or unweighted size of this cache, depending on how the cache was constructed.
      Map<K,​V> hottest​(@org.checkerframework.checker.index.qual.NonNegative int limit)
      Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
      default <T> T hottest​(Function<Stream<Policy.CacheEntry<K,​V>>,​T> mappingFunction)
      Returns the computed result from the ordered traversal of the cache entries.
      default Map<K,​V> hottestWeighted​(@org.checkerframework.checker.index.qual.NonNegative long weightLimit)
      Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
      boolean isWeighted()
      Returns whether the cache is bounded by a maximum size or maximum weight.
      void setMaximum​(@org.checkerframework.checker.index.qual.NonNegative long maximum)
      Specifies the maximum total size of this cache.
      OptionalLong weightedSize()
      Returns the approximate accumulated weight of entries in this cache.
      OptionalInt weightOf​(K key)
      Returns the weight of the entry.

    • Method Detail

      • isWeighted

        boolean isWeighted()
        Returns whether the cache is bounded by a maximum size or maximum weight.
        Returns:
        if the size bounding takes into account the entry's weight

      • weightOf

        OptionalInt weightOf​(K key)
        Returns the weight of the entry. If this cache does not use a weighted size bound or does not support querying for the entry's weight, then the OptionalInt will be empty.
        Parameters:
        key - the key for the entry being queried
        Returns:
        the weight if the entry is present in the cache
        Throws:
        NullPointerException - if the specified key is null

      • weightedSize

        OptionalLong weightedSize()
        Returns the approximate accumulated weight of entries in this cache. If this cache does not use a weighted size bound, then the OptionalLong will be empty.
        Returns:
        the combined weight of the values in this cache

      • getMaximum

        @org.checkerframework.checker.index.qual.NonNegative long getMaximum()
        Returns the maximum total weighted or unweighted size of this cache, depending on how the cache was constructed. This value can be best understood by inspecting isWeighted().
        Returns:
        the maximum size bounding, which may be either weighted or unweighted

      • setMaximum

        void setMaximum​(@org.checkerframework.checker.index.qual.NonNegative long maximum)
        Specifies the maximum total size of this cache. This value may be interpreted as the weighted or unweighted threshold size based on how this cache was constructed. If the cache currently exceeds the new maximum size this operation eagerly evict entries until the cache shrinks to the appropriate size.

        Note that some implementations may have an internal inherent bound on the maximum total size. If the value specified exceeds that bound, then the value is set to the internal maximum.

        Parameters:
        maximum - the maximum, interpreted as weighted or unweighted size depending on how this cache was constructed
        Throws:
        IllegalArgumentException - if the maximum size specified is negative

      • coldest

        Map<K,​V> coldest​(@org.checkerframework.checker.index.qual.NonNegative int limit)
        Returns an unmodifiable snapshot Map view of the cache with ordered traversal. The order of iteration is from the entries least likely to be retained (coldest) to the entries most likely to be retained (hottest). This order is determined by the eviction policy's best guess at the time of creating this snapshot view.

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries within the eviction policy's exclusive lock.

        Parameters:
        limit - the maximum size of the returned map (use Integer.MAX_VALUE to disregard the limit)
        Returns:
        a snapshot view of the cache from the coldest entry to the hottest

      • coldestWeighted

        default Map<K,​V> coldestWeighted​(@org.checkerframework.checker.index.qual.NonNegative long weightLimit)
        Returns an unmodifiable snapshot Map view of the cache with ordered traversal. The order of iteration is from the entries least likely to be retained (coldest) to the entries most likely to be retained (hottest). This order is determined by the eviction policy's best guess at the time of creating this snapshot view. If the cache is bounded by a maximum size rather than a maximum weight, then this method is equivalent to coldest(int).

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries within the eviction policy's exclusive lock.

        Parameters:
        weightLimit - the maximum weight of the returned map (use Long.MAX_VALUE to disregard the limit)
        Returns:
        a snapshot view of the cache from the coldest entry to the hottest

      • coldest

        default <T> T coldest​(Function<Stream<Policy.CacheEntry<K,​V>>,​T> mappingFunction)
        Returns the computed result from the ordered traversal of the cache entries. The order of iteration is from the entries least likely to be retained (coldest) to the entries most likely to be retained (hottest). This order is determined by the eviction policy's best guess at the time of creating this computation.

        Usage example: 

        
   List<K> tenColdestKeys = cache.policy().eviction().orElseThrow()
       .coldest(stream -> stream.map(Map.Entry::getKey).limit(10).toList());

        Beware that this computation is performed within the eviction policy's exclusive lock, so the computation should be short and simple. While the computation is in progress further eviction maintenance will be halted.

        Type Parameters:
        T - the type of the result of the mappingFunction
        Parameters:
        mappingFunction - the mapping function to compute a value
        Returns:
        the computed value
        Throws:
        NullPointerException - if the mappingFunction is null
        RuntimeException - or Error if the mappingFunction does so
        ConcurrentModificationException - if the computation detectably reads or writes an entry in this cache

      • hottest

        Map<K,​V> hottest​(@org.checkerframework.checker.index.qual.NonNegative int limit)
        Returns an unmodifiable snapshot Map view of the cache with ordered traversal. The order of iteration is from the entries most likely to be retained (hottest) to the entries least likely to be retained (coldest). This order is determined by the eviction policy's best guess at the time of creating this snapshot view.

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries within the eviction policy's exclusive lock.

        Parameters:
        limit - the maximum size of the returned map (use Integer.MAX_VALUE to disregard the limit)
        Returns:
        a snapshot view of the cache from the hottest entry to the coldest

      • hottestWeighted

        default Map<K,​V> hottestWeighted​(@org.checkerframework.checker.index.qual.NonNegative long weightLimit)
        Returns an unmodifiable snapshot Map view of the cache with ordered traversal. The order of iteration is from the entries most likely to be retained (hottest) to the entries least likely to be retained (coldest). This order is determined by the eviction policy's best guess at the time of creating this snapshot view. If the cache is bounded by a maximum size rather than a maximum weight, then this method is equivalent to hottest(int).

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries within the eviction policy's exclusive lock.

        Parameters:
        weightLimit - the maximum weight of the returned map (use Long.MAX_VALUE to disregard the limit)
        Returns:
        a snapshot view of the cache from the hottest entry to the coldest

      • hottest

        default <T> T hottest​(Function<Stream<Policy.CacheEntry<K,​V>>,​T> mappingFunction)
        Returns the computed result from the ordered traversal of the cache entries. The order of iteration is from the entries most likely to be retained (hottest) to the entries least likely to be retained (coldest). This order is determined by the eviction policy's best guess at the time of creating this computation.

        Usage example: 

        
   List<K> tenHottestKeys = cache.policy().eviction().orElseThrow()
       .hottest(stream -> stream.map(Map.Entry::getKey).limit(10).toList());

        Beware that this computation is performed within the eviction policy's exclusive lock, so the computation should be short and simple. While the computation is in progress further eviction maintenance will be halted.

        Type Parameters:
        T - the type of the result of the mappingFunction
        Parameters:
        mappingFunction - the mapping function to compute a value
        Returns:
        the computed value
        Throws:
        NullPointerException - if the mappingFunction is null
        RuntimeException - or Error if the mappingFunction does so
        ConcurrentModificationException - if the computation detectably reads or writes an entry in this cache