cuda.core.utils.FileStreamProgramCache#

class cuda.core.utils.FileStreamProgramCache(
path: str | PathLike,
*,
max_size_bytes: int | None = None,
)#

Persistent program cache backed by a directory of atomic files.

Designed for multi-process use: writes stage a temporary file and then os.replace() it into place, so concurrent readers never observe a partially-written entry. There is no cross-process LRU tracking; size enforcement is best-effort by file mtime.

Note

Best-effort writes.

On Windows, os.replace raises PermissionError (winerror 32 / 33) when another process holds the target file open. This backend retries with bounded backoff (~185 ms) and, if still failing, drops the cache write silently and returns success-shaped control flow. The next call will see no entry and recompile. POSIX and other PermissionError codes propagate.

Note

Atomic for readers, not crash-durable.

Each entry’s temp file is fsync-ed before os.replace, but the containing directory is not fsync-ed. A host crash between write and the next directory commit may lose recently added entries; surviving entries remain consistent.

Note

Cross-version sharing.

_FILESTREAM_SCHEMA_VERSION guards on-disk format changes: a cache written by an incompatible version is wiped on open. Within a single schema version, the cache is safe to share across cuda.core patch releases because every entry’s key encodes the relevant backend/compiler/runtime fingerprints for its compilation path (NVRTC entries pin the NVRTC version, NVVM entries pin the libNVVM library and IR versions, PTX/linker entries pin the chosen linker backend and its version – and, when the cuLink/driver backend is selected, the driver version too; nvJitLink-backed PTX entries are deliberately driver-version independent).

Parameters:

  • path – Directory that owns the cache. Created if missing.

  • max_size_bytes – Optional soft cap on total on-disk size. Enforced opportunistically on writes; concurrent writers may briefly exceed it.

Methods

__init__(
path: str | PathLike,
*,
max_size_bytes: int | None = None,
) → None#
clear() → None#

Remove every entry from the cache.

close() → None#

Release backend resources. No-op by default.

get(
key: bytes | str,
default: ObjectCode | None = None,
) → ObjectCode | None#

Return self[key] or default if absent.