synology_apm_repo.sdk.cachemanager module¶
CacheLimits and CacheManager: where every SDK cache’s bound is
declared, and the one place a caller drops caches by name or all at once.
Storage is treated as immutable while a repository is open, so a cache is never
revalidated; CacheManager.invalidate_all() is the deliberate way to pick up
changed storage without reopening the Session.
At the SDK package root beside asynccache: stdlib plus asynccache only,
so every layer can depend on it.
- class synology_apm_repo.sdk.cachemanager.CacheLimits(bucket_readers=16, bucket_readers_interactive=64, chunks=4096, composition_records=64, composition_pages=128, saas_streams=8, dir_scan=256, dir_fixed=64, allocation_tables=256, forward_resolutions=4096)¶
Bases:
objectThe bound of every cache this SDK sizes by count. Each field says what one entry costs, since that is what the number trades against.
- Variables:
bucket_readers (int) –
Pool’s bucket-reader LRU, and the default bound of every private scan cache. A reader holds its parsed header andBucketIndex(9 bytes per chunk, about 72 KiB for a full bucket), plus its ChunkCrcStore values once a CRC check loads them; no open file.bucket_readers_interactive (int) – The same LRU for the
PoolthatRepositoryshares among interactive consumers; one directory listing under a PC/VM disk image can touch several dozen buckets.chunks (int) –
Pool’s decoded-chunk LRU; 4 KiB per entry, 16 MiB total.composition_records (int) – The repo-wide
CompositionRecordLRU. Each record’s page cache is bounded bycomposition_pages, so the worst case is records * pages * 2048 * 20 bytes (about 320 MiB at the defaults); a miss just cold-refetches.composition_pages (int) – Chunk-map pages one record keeps; 2048 entries of 20 bytes (about 40 KiB) per page.
saas_streams (int) –
SaasStreamCacheLRU; each stream holds 2 sqlite connections (snapshot and version files), 4 when a bare placeholder sits beside a numbered generation, so this caps open connections at 2-4x the value.dir_scan (int) – Directory listings of the cache serving bulk-scannable directories (Pool leaves, Composition). A Pool leaf holds up to ~1,030 names, about 265 KiB with the sizes a listing carries, so 256 entries is roughly 66 MiB and covers up to ~8 TiB of unique data when buckets are full.
dir_fixed (int) – Directory listings of the small, fixed set of metadata directories (
db, repo root,suppl_transaction_ids,repo_transactions); kept apart so a scan cannot evict them.allocation_tables (int) –
.infallocation tables, 8 KiB each; only fingerprint verification fills it.forward_resolutions (int) –
SaasStream’s requested-version resolutions; one tiny tuple per entry.
- class synology_apm_repo.sdk.cachemanager.CacheManager¶
Bases:
objectA named registry of cache owners with ordered, collective invalidation.
keyedcreates anAsyncKeyedCacheand registers it in one step, so a cache made this way cannot be left out;registeradds an owner that manages several caches itself (Pool,DirCache,SaasStreamCache). Invalidating runs in reverse registration order, so register a cache after whatever it depends on (aTableafter the connection it is bound to).A cache whose values need closing passes
on_invalidateto close what it drops; no reader may be mid-call while that runs.- keyed(name, fetch=None, *, maxsize, bounded_by='', on_invalidate=None)¶
Create, register and return an
AsyncKeyedCache.- Parameters:
name (str) – Unique registry name.
fetch (Callable[[K], Awaitable] | None) – The cache’s fetch callback.
maxsize (int | None) – Entry bound.
Noneis allowed only withbounded_by.bounded_by (str) – Why a
maxsize=Nonecache cannot grow without limit (for example a closed key set).on_invalidate (Callable[[AsyncKeyedCache], Awaitable[None]] | None) – Async hook run instead of a plain
invalidate(), for a cache whose values need closing.
- Raises:
ValueError –
nameis taken, ormaxsizeisNonewithoutbounded_by.
- register(name, invalidate, stats, *, bounded_by)¶
Register an owner that manages its own cache(s).
- Parameters:
- Raises:
ValueError –
nameis taken orbounded_byis empty.
- names()¶
Registered names, in registration order.
- bounds()¶
{name: what bounds it}, in registration order.
- stats()¶
A snapshot of every registered cache, keyed by cache name.
- async invalidate(*names)¶
Invalidate the named owners, last registered first.
Every named owner is attempted even if an earlier one fails.
- Raises:
KeyError – A name is not registered (nothing was invalidated).
ExceptionGroup – One or more owners failed to invalidate.
- async invalidate_all()¶
Invalidate every registered owner, last registered first.