docs(core.utils): steer callers away from the racy contains+get idiom

Add a note to ``ProgramCacheResource``'s class docstring telling
callers to use ``cache.get(key)`` (or a try/except around
``cache[key]``) rather than the two-call ``if key in cache: data =
cache[key]`` pattern. The two-call pattern is racy across
processes: another writer's ``os.replace`` or an evictor's
``unlink`` can land between the membership check and the read.
``get`` answers both questions in one filesystem operation, so a
successful return always carries the bytes.

Documents the contract rather than building locks or reservations
to "fix" the race -- the right fix is the recommended idiom.
``__contains__`` stays around for diagnostics and tests.

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -135,6 +135,18 @@ class ProgramCacheResource(abc.ABC):
     the binary alone is stored. Callers that need ``symbol_mapping``
     for ``get_kernel(name_expression)`` should compile fresh, or look
     the mangled symbol up by hand.
+
+    .. 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.
     """
 
     @abc.abstractmethod