synology_apm_repo.sdk.asynccache module

AsyncKeyedCache: the SDK’s one key -> value memoizing cache (await a fetch on a miss, store it, optionally evict LRU entries past a cap), so each cache only supplies its fetch function. A stdlib-only leaf that every layer may import.

class synology_apm_repo.sdk.asynccache.CacheStats(size, maxsize, hits, misses, evictions)

Bases: object

A point-in-time snapshot of one AsyncKeyedCache.

Variables:
  • size (int) – Entries currently settled in the cache.

  • maxsize (int | None) – The cache’s bound, or None if unbounded.

  • hits (int) – resolve/lookup calls served from a settled entry.

  • misses (int) – resolve calls that started a fetch, and lookup calls that found nothing; a caller that joins an in-flight fetch counts as neither.

  • evictions (int) – Entries dropped to stay within maxsize.

size: int
maxsize: int | None
hits: int
misses: int
evictions: int
class synology_apm_repo.sdk.asynccache.AsyncKeyedCache(fetch=None, *, maxsize=None)

Bases: Mapping, Generic

A key -> value cache backed by an async fetch callback; resolve is the fetch-and-store operation.

The Mapping interface is a live, read-only view of the settled entries; it never fetches or blocks. maxsize (None = unbounded) may be reassigned; the new cap applies at the next store.

stats()

Counters since construction; invalidate does not reset them.

lookup(key, default)

resolve without the fetch: the settled value for key, counted as a hit and marked most recently used, or default, counted as a miss, for a caller that fetches misses itself. Unlike the Mapping view, this touches recency and the counters.

put(key, value)

Store value for key without a fetch, overwriting any existing entry.

put_many(items)

put for each (key, value) in order, evicting once at the end.

async resolve(key, fetch=None)

The cached value for key, fetched and stored first on a miss; fetch overrides the construction-time fetch for this call. A caller arriving while key is being fetched joins that fetch and gets the same value or exception — except when the caller running that fetch is cancelled: a joiner that isn’t cancelled itself then fetches key anew, and a joiner’s own cancellation never reaches the fetch.

Raises:

TypeError – A fetch is needed and none was bound or passed.

invalidate(key=None)

Drop key (every entry when None); a fetch already in flight for it still answers its waiters but is not stored.

async quiesce()

Wait for every fetch in flight right now and return the exceptions they raised; use it when the values need no closing.

async settle_all()

Wait until no fetch is in flight, including one that starts while this waits, e.g. before closing the values. A caller that calls invalidate() before its next await thus drops exactly the values returned.

Returns every settled value plus every in-flight fetch’s value — including one an invalidate() keeps out of the cache, which still needs closing — and the exceptions of the fetches that failed while this waited. A fetch that already failed when this reaches it is skipped (its owner already got the error). Never starts a fetch; only this task’s own cancellation propagates.