remove __contains__ from ProgramCacheResource and both backends

The ``if key in cache: data = cache[key]`` idiom is racy across
processes (an evictor can unlink the entry between the membership
check and the read), and exposing ``__contains__`` invites that
pattern. ``cache.get(key)`` answers both questions in a single
filesystem-level operation, so a successful return always carries
the bytes.

Drop the abstract method from the ABC and the implementations from
``InMemoryProgramCache`` and ``FileStreamProgramCache``; rewrite
the test suite from ``b"k" in cache`` / ``b"k" not in cache`` to
``cache.get(b"k") is [not] None``.

Class docstring now states the contract explicitly: there is no
``__contains__`` and ``get`` is the recommended lookup. The
``__contains__``-specific LRU/atime tests are deleted; the
``__getitem__`` LRU tests already exercise the relevant
recency-update paths.

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -139,14 +139,14 @@ class ProgramCacheResource(abc.ABC):
     .. note:: **Concurrent-access idiom.**
 
         Use :meth:`get` (or ``data = cache[key]`` inside a ``try /
-        except KeyError``) rather than the two-call pattern ``if key
-        in cache: data = cache[key]``. The two-call pattern is racy
-        across processes: another writer can ``os.replace`` over the
-        entry, or eviction can unlink it, between the membership
-        check and the read. ``get`` answers both questions in a
-        single filesystem-level operation, so a successful return
-        always carries the bytes. ``__contains__`` is provided for
-        diagnostics and tests, not for guarding reads.
+        except KeyError``) for lookups. There is intentionally no
+        ``__contains__``: the obvious ``if key in cache: data =
+        cache[key]`` idiom is racy across processes (another writer
+        can ``os.replace`` over the entry, or eviction can unlink
+        it, between the check and the read), and exposing
+        ``__contains__`` invites that pattern. ``get`` answers
+        both questions in one filesystem-level operation, so a
+        successful return always carries the bytes.
     """
 
     @abc.abstractmethod
@@ -167,10 +167,6 @@ def __setitem__(self, key: bytes | str, value: bytes | bytearray | memoryview |
         write time so the cached entry holds the bytes, not a path.
         """
 
-    @abc.abstractmethod
-    def __contains__(self, key: bytes | str) -> bool:
-        """Return ``True`` if ``key`` is in the cache."""
-
     @abc.abstractmethod
     def __delitem__(self, key: bytes | str) -> None:
         """Remove the entry associated with ``key``.
@@ -936,9 +932,10 @@ class InMemoryProgramCache(ProgramCacheResource):
 
     Notes
     -----
-    Recency is updated on :meth:`__getitem__`; :meth:`__contains__` is
-    read-only and does not shift LRU order, matching
-    :class:`FileStreamProgramCache`.
+    Recency is updated on :meth:`__getitem__`; ``get`` is the
+    recommended lookup since the cache deliberately omits
+    ``__contains__`` (the ``if key in cache: ...`` idiom is racy
+    across processes; see :class:`ProgramCacheResource`).
 
     Thread safety: a :class:`threading.RLock` serialises every method,
     so the cache can be shared across threads without external
@@ -986,14 +983,6 @@ def __setitem__(self, key: object, value: bytes | bytearray | memoryview | Objec
             self._total_bytes += size
             self._evict_to_caps()
 
-    def __contains__(self, key: object) -> bool:
-        # Validate the key (mirror FileStream's behaviour: a non-str,
-        # non-bytes key is a programming error and should surface, not
-        # quietly report "not present").
-        k = _as_key_bytes(key)
-        with self._lock:
-            return k in self._entries
-
     def __delitem__(self, key: object) -> None:
         k = _as_key_bytes(key)
         with self._lock:
@@ -1418,24 +1407,6 @@ def _path_for_key(self, key: object) -> Path:
 
     # -- mapping API ---------------------------------------------------------
 
-    def __contains__(self, key: object) -> bool:
-        # Membership is a stat-only check: it must not read the payload (a
-        # full file read just to answer ``key in cache`` is wasteful) and
-        # must not bump atime (otherwise probing keeps cold entries hot
-        # and skews LRU eviction).
-        #
-        # Like every cross-process file lookup, ``key in cache`` followed
-        # by ``cache[key]`` is inherently racy: the entry may be evicted
-        # by another process between the two calls. The previous version
-        # of this method routed through ``__getitem__`` and did a full
-        # read; that did not close the race (the file could vanish between
-        # the read and the next caller's read), it just paid the cost
-        # twice. The cache layer does no payload validation -- entries
-        # are raw binary, not framed records -- so a successful ``exists``
-        # check is the same answer ``__getitem__`` would give for a
-        # non-racing caller.
-        return self._path_for_key(key).exists()
-
     def __getitem__(self, key: object) -> bytes:
         path = self._path_for_key(key)
         try:

cuda_core/tests/test_program_cache.py

@@ -763,7 +763,7 @@ def _flaky_unlink(self, *args, **kwargs):
         monkeypatch.setattr(Path, "unlink", _flaky_unlink)
         del cache[b"k"]  # succeeds on third attempt
         assert calls["n"] == 3
-        assert b"k" not in cache
+        assert cache.get(b"k") is None
 
 
 def test_filestream_cache_unlink_propagates_non_windows_permission_error(tmp_path, monkeypatch):
@@ -1223,7 +1223,7 @@ def test_filestream_cache_empty_on_create(tmp_path):
 
     with FileStreamProgramCache(tmp_path / "fc") as cache:
         assert len(cache) == 0
-        assert b"nope" not in cache
+        assert cache.get(b"nope") is None
         with pytest.raises(KeyError):
             cache[b"nope"]
 
@@ -1236,7 +1236,7 @@ def test_filestream_cache_roundtrip(tmp_path):
 
     with FileStreamProgramCache(tmp_path / "fc") as cache:
         cache[b"k1"] = _fake_object_code(b"v1", name="x")
-        assert b"k1" in cache
+        assert cache.get(b"k1") is not None
         assert cache[b"k1"] == b"v1"
 
 
@@ -1246,7 +1246,7 @@ def test_filestream_cache_delete(tmp_path):
     with FileStreamProgramCache(tmp_path / "fc") as cache:
         cache[b"k"] = _fake_object_code()
         del cache[b"k"]
-        assert b"k" not in cache
+        assert cache.get(b"k") is None
         with pytest.raises(KeyError):
             del cache[b"k"]
 
@@ -1281,31 +1281,6 @@ def test_filestream_cache_persists_across_reopen(tmp_path):
         assert cache[b"k"] == b"persisted"
 
 
-def test_filestream_cache_contains_does_not_read_or_promote_lru(tmp_path):
-    """``__contains__`` is a stat-only check: it must not read the payload
-    (a full file read just to answer membership is wasteful) and must not
-    bump atime (otherwise probing keeps cold entries hot and inverts LRU
-    eviction relative to genuine reads)."""
-    from cuda.core.utils import FileStreamProgramCache
-
-    cap = 250
-    with FileStreamProgramCache(tmp_path / "fc", max_size_bytes=cap) as cache:
-        cache[b"a"] = b"a" * 100
-        cache[b"b"] = b"b" * 100
-
-        # Hammer membership for 'a' (cold) -- must NOT promote it.
-        for _ in range(50):
-            assert b"a" in cache
-
-        # The next size-cap-triggering write should evict 'a' (the genuinely
-        # oldest by atime). If membership had bumped atime, 'b' would evict
-        # instead.
-        cache[b"c"] = b"c" * 100
-        assert b"a" not in cache
-        assert b"b" in cache
-        assert b"c" in cache
-
-
 def test_filestream_cache_permission_error_propagates_on_posix(tmp_path, monkeypatch):
     """On non-Windows, PermissionError from os.replace is a real config error
     and must not be silently swallowed."""
@@ -1376,7 +1351,7 @@ def _denied(src, dst):
                 cache[b"k"] = _fake_object_code(b"v")
         else:
             cache[b"k"] = _fake_object_code(b"v")  # swallowed
-            assert b"k" not in cache
+            assert cache.get(b"k") is None
 
 
 def test_filestream_cache_atomic_no_half_written_file(tmp_path, monkeypatch):
@@ -1394,7 +1369,7 @@ def _boom(src, dst):
         with pytest.raises(RuntimeError, match="crash"):
             cache[b"k"] = _fake_object_code(b"v")
         monkeypatch.undo()
-        assert b"k" not in cache
+        assert cache.get(b"k") is None
 
 
 def test_filestream_cache_prune_only_if_stat_unchanged(tmp_path):
@@ -1803,8 +1778,8 @@ def test_filestream_cache_size_cap_counts_tmp_files(tmp_path):
         # the temp file's bytes count toward the cap now.
         time.sleep(0.02)
         cache[b"c"] = _fake_object_code(b"C" * 200, name="c")
-        assert b"a" not in cache
-        assert b"c" in cache
+        assert cache.get(b"a") is None
+        assert cache.get(b"c") is not None
 
 
 def test_filestream_cache_handles_long_keys(tmp_path):
@@ -1818,8 +1793,8 @@ def test_filestream_cache_handles_long_keys(tmp_path):
     with FileStreamProgramCache(tmp_path / "fc") as cache:
         cache[long_bytes_key] = _fake_object_code(b"b", name="nb")
         cache[long_str_key] = _fake_object_code(b"s", name="ns")
-        assert long_bytes_key in cache
-        assert long_str_key in cache
+        assert cache.get(long_bytes_key) is not None
+        assert cache.get(long_str_key) is not None
         assert cache[long_bytes_key] == b"b"
         assert cache[long_str_key] == b"s"
 
@@ -1829,8 +1804,8 @@ def test_filestream_cache_accepts_str_keys(tmp_path):
 
     with FileStreamProgramCache(tmp_path / "fc") as cache:
         cache["my-key"] = _fake_object_code(b"v")
-        assert "my-key" in cache
-        assert b"my-key" in cache
+        assert cache.get("my-key") is not None
+        assert cache.get(b"my-key") is not None
 
 
 def test_filestream_cache_size_cap_evicts_oldest(tmp_path):
@@ -1848,8 +1823,8 @@ def test_filestream_cache_size_cap_evicts_oldest(tmp_path):
         cache[b"c"] = b"C" * 2000
 
     with FileStreamProgramCache(root, max_size_bytes=cap) as cache:
-        assert b"a" not in cache
-        assert b"c" in cache
+        assert cache.get(b"a") is None
+        assert cache.get(b"c") is not None
 
 
 def test_filestream_cache_atime_lru_promotes_recently_read(tmp_path):
@@ -1874,10 +1849,10 @@ def test_filestream_cache_atime_lru_promotes_recently_read(tmp_path):
 
     with FileStreamProgramCache(root, max_size_bytes=cap) as cache:
         # 'b' is now the oldest atime -- evicted.
-        assert b"b" not in cache
+        assert cache.get(b"b") is None
         # 'a' was read after 'b' so its atime is newer -- survives.
-        assert b"a" in cache
-        assert b"c" in cache
+        assert cache.get(b"a") is not None
+        assert cache.get(b"c") is not None
 
 
 def test_filestream_cache_unbounded_by_default(tmp_path):
@@ -1952,12 +1927,12 @@ def test_cache_roundtrip_with_real_compilation(tmp_path, init_cuda):
 
     # First "process": compile and store the binary.
     with FileStreamProgramCache(tmp_path / "fc") as cache:
-        assert key not in cache
+        assert cache.get(key) is None
         cache[key] = compiled  # extracts bytes(compiled.code)
 
     # Second "process": reopen, retrieve bytes, rebuild ObjectCode.
     with FileStreamProgramCache(tmp_path / "fc") as cache:
-        assert key in cache
+        assert cache.get(key) is not None
         cached_bytes = cache[key]
 
     assert cached_bytes == bytes(compiled.code)
@@ -1976,7 +1951,7 @@ def test_inmemory_cache_empty_on_create():
 
     cache = InMemoryProgramCache()
     assert len(cache) == 0
-    assert b"nope" not in cache
+    assert cache.get(b"nope") is None
     with pytest.raises(KeyError):
         cache[b"nope"]
 
@@ -1986,7 +1961,7 @@ def test_inmemory_cache_roundtrip_object_code():
 
     cache = InMemoryProgramCache()
     cache[b"k1"] = _fake_object_code(b"v1", name="x")
-    assert b"k1" in cache
+    assert cache.get(b"k1") is not None
     assert cache[b"k1"] == b"v1"
 
 
@@ -2032,8 +2007,8 @@ def test_inmemory_cache_str_and_bytes_keys_alias():
     cache = InMemoryProgramCache()
     cache["k"] = b"v"
     assert cache[b"k"] == b"v"
-    assert b"k" in cache
-    assert "k" in cache
+    assert cache.get(b"k") is not None
+    assert cache.get("k") is not None
 
 
 def test_inmemory_cache_rejects_non_str_non_bytes_key():
@@ -2045,7 +2020,7 @@ def test_inmemory_cache_rejects_non_str_non_bytes_key():
     with pytest.raises(TypeError):
         cache[123]
     with pytest.raises(TypeError):
-        123 in cache  # noqa: B015
+        cache.get(123)
 
 
 def test_inmemory_cache_rejects_non_bytes_non_object_code_value():
@@ -2062,7 +2037,7 @@ def test_inmemory_cache_delete():
     cache = InMemoryProgramCache()
     cache[b"k"] = _fake_object_code()
     del cache[b"k"]
-    assert b"k" not in cache
+    assert cache.get(b"k") is None
     with pytest.raises(KeyError):
         del cache[b"k"]
 
@@ -2085,7 +2060,7 @@ def test_inmemory_cache_clear():
     cache[b"b"] = _fake_object_code()
     cache.clear()
     assert len(cache) == 0
-    assert b"a" not in cache
+    assert cache.get(b"a") is None
 
 
 def test_inmemory_cache_get_returns_default_on_miss():
@@ -2146,9 +2121,9 @@ def test_inmemory_cache_size_cap_evicts_oldest():
     cache[b"a"] = b"a" * 100
     cache[b"b"] = b"b" * 100
     cache[b"c"] = b"c" * 100  # forces eviction of b"a"
-    assert b"a" not in cache
-    assert b"b" in cache
-    assert b"c" in cache
+    assert cache.get(b"a") is None
+    assert cache.get(b"b") is not None
+    assert cache.get(b"c") is not None
 
 
 def test_inmemory_cache_read_promotes_lru():
@@ -2160,25 +2135,9 @@ def test_inmemory_cache_read_promotes_lru():
     # Read of a promotes it past b in LRU order.
     _ = cache[b"a"]
     cache[b"c"] = b"c" * 100  # b is now the oldest; b should evict
-    assert b"a" in cache
-    assert b"b" not in cache
-    assert b"c" in cache
-
-
-def test_inmemory_cache_contains_does_not_promote_lru():
-    """``__contains__`` is read-only and must not shift LRU order, mirroring
-    FileStream semantics."""
-    from cuda.core.utils import InMemoryProgramCache
-
-    cache = InMemoryProgramCache(max_size_bytes=250)
-    cache[b"a"] = b"a" * 100
-    cache[b"b"] = b"b" * 100
-    # Membership check must NOT promote a in LRU.
-    assert b"a" in cache
-    cache[b"c"] = b"c" * 100  # a is still oldest -> a evicts
-    assert b"a" not in cache
-    assert b"b" in cache
-    assert b"c" in cache
+    assert cache.get(b"a") is not None
+    assert cache.get(b"b") is None
+    assert cache.get(b"c") is not None
 
 
 def test_inmemory_cache_oversized_write_evicts_itself():
@@ -2188,7 +2147,7 @@ def test_inmemory_cache_oversized_write_evicts_itself():
 
     cache = InMemoryProgramCache(max_size_bytes=10)
     cache[b"big"] = b"x" * 100
-    assert b"big" not in cache
+    assert cache.get(b"big") is None
     assert len(cache) == 0
 
 

cuda_core/tests/test_program_cache_multiprocess.py

@@ -84,7 +84,7 @@ def test_concurrent_writers_distinct_keys_all_survive(tmp_path):
         for base in range(n_procs):
             for i in range(per_proc):
                 key = f"proc-{base}-key-{i}".encode()
-                assert key in cache
+                assert cache.get(key) is not None
 
 
 def test_concurrent_reader_never_sees_torn_file(tmp_path):