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: object

The 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 and BucketIndex (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 Pool that Repository shares 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 CompositionRecord LRU. Each record’s page cache is bounded by composition_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) – SaasStreamCache LRU; 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) – .inf allocation tables, 8 KiB each; only fingerprint verification fills it.

  • forward_resolutions (int) – SaasStream’s requested-version resolutions; one tiny tuple per entry.

bucket_readers: int
bucket_readers_interactive: int
chunks: int
composition_records: int
composition_pages: int
saas_streams: int
dir_scan: int
dir_fixed: int
allocation_tables: int
forward_resolutions: int
class synology_apm_repo.sdk.cachemanager.CacheManager

Bases: object

A named registry of cache owners with ordered, collective invalidation.

keyed creates an AsyncKeyedCache and registers it in one step, so a cache made this way cannot be left out; register adds 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 (a Table after the connection it is bound to).

A cache whose values need closing passes on_invalidate to 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. None is allowed only with bounded_by.

  • bounded_by (str) – Why a maxsize=None cache 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 – name is taken, or maxsize is None without bounded_by.

register(name, invalidate, stats, *, bounded_by)

Register an owner that manages its own cache(s).

Parameters:
  • name (str) – Unique registry name.

  • invalidate (Callable[[], Awaitable[None] | None]) – Drops the owner’s caches; may be sync or async.

  • stats (Callable[[], Mapping[str, CacheStats]]) – Snapshot of the owner’s caches, keyed by cache name.

  • bounded_by (str) – What bounds the owner’s caches.

Raises:

ValueError – name is taken or bounded_by is 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.