loom.core.cache.dependency

Classes

GenerationalDependencyResolver(cache)

Generational tags with monotonic counters in cache backend.

class loom.core.cache.dependency.GenerationalDependencyResolver(cache)

Bases: DependencyResolver, BatchFingerprintResolver

Generational tags with monotonic counters in cache backend.

A mutation bumps only the tags it affects (see bump_from_events()), so updating one row leaves every other cached row of the same entity warm. The bare entity tag stays in every key’s tag list but the framework never bumps it: it is the manual entity-wide flush handle. An operator increments tag:<entity> by hand to evict every key of that entity at once.

Parameters:

cache (CacheBackend)

async fingerprint(tags)

Compute a composite fingerprint from generation counters of all tags.

Parameters:

tags (list[str]) – Dependency tag names.

Returns:

A stable hash representing the combined tag generation state.

Return type:

str

async fingerprint_many(tag_groups)

Compute one fingerprint per tag group, reading every counter once.

The distinct tags of every group are read together, in batches, so the cost is one round trip per COUNTER_BATCH_SIZE distinct tags instead of one per group.

Parameters:

tag_groups (Sequence[list[str]]) – Dependency tag names, grouped per entity.

Returns:

One fingerprint per group, in input order; each value is identical to what fingerprint() returns for the same group.

Return type:

list[str]

async bump_from_events(events)

Increment generation counters for the tags affected by mutation events.

Every event bumps entity:list and entity:id:<k> per id; the event’s own tags are bumped as they come. The bare entity tag is never bumped by the framework: it is reserved for a manual entity-wide flush.

The counters are bumped concurrently rather than one round trip at a time: with K distinct tags, a sequential loop pays K round trips in series, while awaiting them together pays roughly one round trip regardless of K once the backend is network-bound (see the benchmark referenced in the PR that introduced this).

Parameters:

events (tuple[MutationEvent, ...]) – Mutation events to process.

Return type:

None

entity_tags(entity, entity_id)

Return dependency tags for a single entity lookup.

Parameters:

• entity (str) – Normalized entity name.

• entity_id (object | None) – Primary key of the entity, or None.

Returns:

List of tag names for this entity.

Return type:

list[str]

list_tags(entity, filter_fingerprint)

Return dependency tags for a list/index query.

Parameters:

• entity (str) – Normalized entity name.

• filter_fingerprint (str) – Hash of the applied filter parameters.

Returns:

List of tag names for this list query.

Return type:

list[str]