Class AsyncCache<K,V>

java.lang.Object
lol.trq.alts.cache.AsyncCache<K,V>
Type Parameters:
K - the lookup key (e.g. a player UUID string)
V - the cached value (e.g. a stats record)

public final class AsyncCache<K,V> extends Object
A lazy, non-blocking, per-key value cache. get(Object) never blocks: on a cache miss it returns null and fires a background fetch, so a later call (e.g. the next frame) sees the filled value. This is the data-only distillation of SkinAvatarCache — it drops the GPU/main-thread upload step, since plain data needs no marshalling.

Each key sits in one of these states, each a real marker object because a ConcurrentHashMap forbids null values:

  • absent → never requested
  • pending → a first fetch is in flight
  • failed → the last fetch threw or returned null, and no value was ever held. Retried once a backoff elapses — it grows with each consecutive failure — or at once after invalidate(Object)
  • a hit → a value with the time it was fetched at

With a positive ttlMillis the cache is stale-while-revalidate: once an entry ages past the TTL, get(Object) keeps returning the stale value and kicks off a refresh in the background, so the UI never flickers to empty. A refresh that fails leaves the stale value in place and is tried again after the same growing backoff: a value that was good a moment ago is a better answer than nothing, and a service having a bad minute must not blank every entry that happened to expire during it.

The cache is bounded. Past maxEntries, the entries read longest ago are dropped, so a host that looks up an ever-growing set of keys holds a fixed amount rather than all of them for the life of the process.

The loader runs on the executor the cache was given (for the runtime's game-stats caches, the runtime's executor), so it may block. It must be thread-safe and should return null (or throw) to signal failure.

Since:
0.1.0
  • Field Details

    • DEFAULT_MAX_ENTRIES

      public static final int DEFAULT_MAX_ENTRIES
      The entry bound a cache gets when none is given.
      Since:
      0.12.0
      See Also:
  • Constructor Details

    • AsyncCache

      public AsyncCache(Executor executor, Function<K,V> loader)
      Creates a cache whose entries never expire (refresh only via invalidate(Object)).
      Parameters:
      executor - the executor the loader runs on; never the common pool unless the caller says so
      loader - the background fetch; returns null or throws to mark a key failed
      Since:
      1.0.0
    • AsyncCache

      public AsyncCache(Executor executor, Function<K,V> loader, long ttlMillis)
      Creates a cache with stale-while-revalidate expiry, holding at most DEFAULT_MAX_ENTRIES.
      Parameters:
      executor - the executor the loader runs on
      loader - the background fetch; returns null or throws to mark a key failed
      ttlMillis - how long a fetched value is fresh, in milliseconds; <= 0 never expires
      Since:
      1.0.0
    • AsyncCache

      public AsyncCache(Executor executor, Function<K,V> loader, long ttlMillis, int maxEntries)
      Creates a cache with stale-while-revalidate expiry and a given entry bound.
      Parameters:
      executor - the executor the loader runs on
      loader - the background fetch; returns null or throws to mark a key failed
      ttlMillis - how long a fetched value is fresh, in milliseconds; <= 0 never expires
      maxEntries - the most entries to hold before the least recently read are dropped; at least 1
      Since:
      1.0.0
  • Method Details

    • get

      public V get(K key)
      Returns the cached value for key if present, otherwise null. On a miss this starts a background fetch; on a stale hit it serves the stale value and refreshes in the background; on a past failure whose backoff has elapsed it tries again.
      Parameters:
      key - the lookup key
      Returns:
      the value if ready (possibly stale), or null while pending, failed, or just requested
      Since:
      0.1.0
    • invalidate

      public void invalidate(K key)
      Drops the entry for key so the next get(Object) refetches it. Use to force a refresh, or to retry a failed key without waiting out its backoff.
      Parameters:
      key - the key to evict
      Since:
      0.1.0
    • clear

      public void clear()
      Drops every entry.
      Since:
      0.1.0
    • size

      public int size()
      Returns how many keys the cache currently tracks, counting those pending or failed.
      Returns:
      the entry count
      Since:
      0.12.0