Class AsyncReadThroughCache<K,V>

java.lang.Object
com.loomcache.client.cache.AsyncReadThroughCache<K,V>
Type Parameters:
K - key type
V - value type
All Implemented Interfaces:
AutoCloseable
public class AsyncReadThroughCache<K,V> extends Object implements AutoCloseable
Asynchronous read-through cache that implements the cache-aside pattern with non-blocking loads.

When a cache miss occurs, the AsyncCacheLoader is called to fetch the value asynchronously. All returned futures are completed on a bounded executor.

Multiple concurrent requests for the same missing key are coalesced (single-flight): only one loader call is made, and all callers receive the same CompletableFuture result. This eliminates redundant upstream calls under heavy concurrent access patterns. Uses a bounded executor for async operations with caller-runs backpressure.

See Also:

  • Constructor Details

    • AsyncReadThroughCache

      public AsyncReadThroughCache(NearCache<K,V> nearCache, AsyncCacheLoader<K,V> loader)
      Create a new async read-through cache.
      Parameters:
      nearCache - the underlying near cache (must not be null)
      loader - the async cache loader for cache misses (must not be null)
      Throws:
      NullPointerException - if any parameter is null

  • Method Details

    • getAsync

      public CompletableFuture<V> getAsync(K key)
      Asynchronously get a value from the cache, loading it if necessary.

      If multiple callers request the same missing key simultaneously, only one loader call is made; all callers receive the same future (single-flight).

      Parameters:
      key - the key to retrieve (must not be null)
      Returns:
      a future that completes with the cached or loaded value
      Throws:
      NullPointerException - if key is null

    • getAllAsync

      public CompletableFuture<Map<K,V>> getAllAsync(Collection<K> keys)
      Asynchronously get multiple values, loading any missing ones efficiently.

      Hits are resolved immediately from the near cache. Misses are loaded using AsyncCacheLoader.loadAllAsync(Collection) and cached on completion. In-flight loads for individual keys are still coalesced.

      Parameters:
      keys - the keys to retrieve (must not be null)
      Returns:
      a future that completes with a map of keys to values (may be partial if some loads fail)
      Throws:
      NullPointerException - if keys is null

    • refreshAsync

      public CompletableFuture<V> refreshAsync(K key)
      Asynchronously refresh a specific key by forcing a reload from the source.

      Invalidates the near cache entry first, then triggers a fresh load. Does not participate in single-flight coalescing — a fresh load is always issued.

      Parameters:
      key - the key to refresh (must not be null)
      Returns:
      a future that completes with the refreshed value
      Throws:
      NullPointerException - if key is null

    • refreshAll

      public void refreshAll()
      Refresh all entries by clearing the near cache.

    • getStats

      public NearCache.NearCacheStats getStats()
      Get underlying near cache statistics.

    • close

      public void close()
      Shuts down the async executor. After calling this method, new async loads will be rejected.
      Specified by:
      close in interface AutoCloseable