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)
      Returns the cached value, updating access bookkeeping, or null if the key is absent.

    • 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)
      Returns whether an entry exists for the key without updating access bookkeeping.

    • remove

      public V remove(K key)
      Removes the entry and reports a manual eviction; returns its former value or null when absent.

    • 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()
      Removes all entries and delivers manual-eviction notifications after releasing the cache lock.

    • size

      public int size()
      Returns the current number of cached entries.

    • weight

      public long weight()
      Returns the total weight currently accounted for by the cache.

    • keys

      public List<K> keys()
      Returns an independent snapshot of the cached keys.

    • firstKey

      public K firstKey()
      Returns the lowest key according to the configured key ordering, or null when empty or no ordering is configured.

    • lastKey

      public K lastKey()
      Returns the highest key according to the configured key ordering, or null when empty or no ordering is configured.

    • maxWeight

      public long maxWeight()
      Returns the configured maximum total cache weight.

    • maxEntryWeight

      public long maxEntryWeight()
      Returns the configured maximum weight for a single entry.

    • 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)
      Registers an eviction listener and returns a registration that removes it when cancelled.

    • 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