Add Multiton.clear_cache with type and key filters

[sjperkins]

Adds a public way to evict cached Multiton instances, motivated by ratt-ru/xarray-ms#177 (part 2: no public, per-measurement-set way to evict cached tables).

Changes

• Multiton.clear_cache(instance_type=None, *, where=None) -> int
  • With no filters, clears the whole cache and the expiry heap.
  • instance_type matches with isinstance (a type, tuple of types or union, subclasses included).
  • where(instance) matches on the cached instance itself, so callers can evict only instances tied to a particular resource, e.g. one dataset's table handles, while leaving other entries (such as an expensive derived structure) cached.
  • Filters combine with AND. Returns the number of entries evicted.

Like release(), clear_cache doesn't wait for constructions already in progress.

Intended use in xarray-ms

def _ms_tables(obj):
  return isinstance(obj, Table) and os.path.abspath(obj.name()) == os.path.abspath(ms)

Multiton.clear_cache(where=_ms_tables)

This is independent of part 1 of that issue (memory retained per MSv2Structure build). That was a reference leak in arcae's merge_np_partitions, fixed in ska-sa/arcae#244. release(ms) still avoids an unnecessary structure rebuild when only the table handles need reopening.

Tests

New tests cover full and filtered clears, subclass/tuple/union matching, where with AND semantics, the return count, stale heap entries after a clear, and a per-dataset eviction that mirrors xarray-ms's table/subtable/structure layout.

🤖 Generated with Claude Code