cuda.core.utils.make_program_cache_key#

cuda.core.utils.make_program_cache_key(
*,
code: str | bytes,
code_type: str,
options: ProgramOptions,
target_type: str,
name_expressions: Sequence[str | bytes | bytearray] = (),
extra_digest: bytes | None = None,
) → bytes#

Build a stable cache key from compile inputs.

Parameters:

  • code – Source text. str is encoded as UTF-8.

  • code_type – One of "c++", "ptx", "nvvm".

  • options – A cuda.core.ProgramOptions. Its arch must be set (the default ProgramOptions.__post_init__ populates it from the current device).

  • target_type – One of "ptx", "cubin", "ltoir".

  • name_expressions – Optional iterable of mangled-name lookups. Order is not significant. Elements may be str, bytes, or bytearray; "foo" and b"foo" produce distinct keys because Program.compile records the original Python object as the ObjectCode.symbol_mapping key, and get_kernel lookups must use the same type the cache key recorded.

  • extra_digest – Caller-supplied bytes mixed into the key. Required whenever cuda.core.ProgramOptions sets any option that pulls in external file content (include_path, pre_include, pch, use_pch, pch_dir) – the cache cannot read those files on the caller’s behalf, so the caller must fingerprint the header / PCH surface and pass it here. Callers may pass this for other inputs too (embedded kernels, generated sources, etc.).

Returns:

A 32-byte blake2b digest suitable for use as a cache key.

Return type:

bytes

Raises:

  • ValueError – If options sets an option with compile-time side effects (such as create_pch) – a cache hit skips compilation, so the side effect would not occur.

  • ValueError – If extra_digest is None while options sets any option whose compilation effect depends on external file content that the key cannot otherwise observe.