Class MemoryAwareCacheSupport<K,V>

java.lang.Object
io.fluxzero.common.caching.MemoryAwareCacheSupport<K,V>
Type Parameters:
K - key type
V - value type
All Implemented Interfaces:
AutoCloseable
public class MemoryAwareCacheSupport<K,V> extends Object implements AutoCloseable
A hard-reference, weighted cache with LRU eviction and optional key ordering.

The cache intentionally avoids soft references. Memory ownership is explicit through entry weights and a maximum total weight. A MemoryPressureController may request extra trimming when heap or GC pressure is observed.

  • Field Details

    • DEFAULT_MEMORY_PRESSURE_CHECK_INTERVAL

      public static final Duration DEFAULT_MEMORY_PRESSURE_CHECK_INTERVAL

  • Constructor Details

    • MemoryAwareCacheSupport

      public MemoryAwareCacheSupport(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super K, ? super V> weigher)

    • MemoryAwareCacheSupport

      public MemoryAwareCacheSupport(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super K, ? super V> weigher, Comparator<? super K> keyComparator)

    • MemoryAwareCacheSupport

      public MemoryAwareCacheSupport(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super K, ? super V> weigher, Comparator<? super K> keyComparator, MemoryPressureController memoryPressureController)

    • MemoryAwareCacheSupport

      public MemoryAwareCacheSupport(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super K, ? super V> weigher, Comparator<? super K> keyComparator, MemoryPressureController memoryPressureController, Duration memoryPressureCheckInterval)

  • Method Details

    • put

      public boolean put(K key, V value)
      Stores a value when it fits the configured entry and total weight constraints.
      Returns:
      true if the value remains cached after admission and eviction

    • putAll

      public void putAll(Map<? extends K, ? extends V> values)
      Stores all values in iteration order while applying the same admission and weight constraints as put(Object, Object).

      The cache is mutated under one lock and memory pressure is checked once after the full batch, rather than once per entry.

      Parameters:
      values - values to store by cache key

    • get

      public V get(K key)

    • containsKey

      public boolean containsKey(K key)

    • remove

      public V remove(K key)

    • evict

      public V evict(K key, MemoryAwareCacheSupportEviction.Reason reason)
      Removes a value and publishes the supplied eviction reason when the key was present.

    • clear

      public void clear()

    • size

      public int size()

    • weight

      public long weight()

    • keys

      public List<K> keys()

    • firstKey

      public K firstKey()

    • lastKey

      public K lastKey()

    • maxWeight

      public long maxWeight()

    • maxEntryWeight

      public long maxEntryWeight()

    • valuesFrom

      public List<V> valuesFrom(K minKey, boolean inclusive, int maxSize)
      Returns cached values ordered by key, starting at minKey.

    • evictBefore

      public void evictBefore(K frontier, boolean inclusive)
      Evicts all ordered keys before the supplied frontier.

    • registerEvictionListener

      public Registration registerEvictionListener(Consumer<MemoryAwareCacheSupportEviction<K,V>> listener)

    • trimForMemoryPressure

      public boolean trimForMemoryPressure()
      Proactively sheds cached weight according to the configured trim ratio and maximum trim weight when the controller observes memory pressure.
      Returns:
      true if pressure was observed

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable