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

  • 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

    • updateAll

      public <U> void updateAll(Map<? extends K, ? extends U> updates, BiFunction<? super U, ? super V, ? extends V> updateFunction)
      Applies independent updates under one cache lock and checks memory pressure once after the batch.

      Iteration order, admission, size eviction and manual-removal notifications are identical to applying the updates individually. The batch as a whole is not an atomic transaction.

    • updateAll

      public <U> void updateAll(Iterable<? extends U> updates, Function<? super U, ? extends K> keyFunction, BiFunction<? super U, ? super V, ? extends V> updateFunction)
      Applies ordered updates under one cache lock and checks memory pressure once after the batch. Repeated keys are applied in iteration order.

    • updateAll

      public <U> void updateAll(Iterable<? extends U> updates, Function<? super U, ? extends K> lookupKeyFunction, Function<? super U, ? extends K> retainedKeyFunction, BiFunction<? super U, ? super V, ? extends V> updateFunction)
      Applies ordered updates while retaining a stable key only when an update inserts a new mapping. Repeated keys are applied in iteration order.

    • get

      public V get(K key)

    • supplyAll

      public <U> void supplyAll(Iterable<? extends U> lookups, Function<? super U, ? extends K> keyFunction, BiConsumer<? super U, ? super V> valueConsumer)
      Supplies present values for an ordered group of lookups under one cache lock. Every hit retains the same LRU and cross-cache access bookkeeping as get(Object).

    • 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