Class AsyncCache<K,V>
- Type Parameters:
K- the lookup key (e.g. a player UUID string)V- the cached value (e.g. a stats record)
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 afterinvalidate(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 Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe entry bound a cache gets when none is given. -
Constructor Summary
ConstructorsConstructorDescriptionAsyncCache(Executor executor, Function<K, V> loader) Creates a cache whose entries never expire (refresh only viainvalidate(Object)).AsyncCache(Executor executor, Function<K, V> loader, long ttlMillis) Creates a cache with stale-while-revalidate expiry, holding at mostDEFAULT_MAX_ENTRIES.AsyncCache(Executor executor, Function<K, V> loader, long ttlMillis, int maxEntries) Creates a cache with stale-while-revalidate expiry and a given entry bound. -
Method Summary
Modifier and TypeMethodDescriptionvoidclear()Drops every entry.Returns the cached value forkeyif present, otherwisenull.voidinvalidate(K key) Drops the entry forkeyso the nextget(Object)refetches it.intsize()Returns how many keys the cache currently tracks, counting those pending or failed.
-
Field Details
-
DEFAULT_MAX_ENTRIES
public static final int DEFAULT_MAX_ENTRIESThe entry bound a cache gets when none is given.- Since:
- 0.12.0
- See Also:
-
-
Constructor Details
-
AsyncCache
Creates a cache whose entries never expire (refresh only viainvalidate(Object)).- Parameters:
executor- the executor the loader runs on; never the common pool unless the caller says soloader- the background fetch; returnsnullor throws to mark a key failed- Since:
- 1.0.0
-
AsyncCache
Creates a cache with stale-while-revalidate expiry, holding at mostDEFAULT_MAX_ENTRIES.- Parameters:
executor- the executor the loader runs onloader- the background fetch; returnsnullor throws to mark a key failedttlMillis- how long a fetched value is fresh, in milliseconds;<= 0never expires- Since:
- 1.0.0
-
AsyncCache
Creates a cache with stale-while-revalidate expiry and a given entry bound.- Parameters:
executor- the executor the loader runs onloader- the background fetch; returnsnullor throws to mark a key failedttlMillis- how long a fetched value is fresh, in milliseconds;<= 0never expiresmaxEntries- the most entries to hold before the least recently read are dropped; at least 1- Since:
- 1.0.0
-
-
Method Details
-
get
Returns the cached value forkeyif present, otherwisenull. 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
nullwhile pending, failed, or just requested - Since:
- 0.1.0
-
invalidate
Drops the entry forkeyso the nextget(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
-