fixup! feat(core.utils): per-field linker gates + use_libdevice truthy gate

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -215,9 +215,62 @@ def _backend_for_code_type(code_type: str) -> str:
 )
 
 
+# Map each linker-relevant ProgramOptions field to the gate the Linker uses
+# to turn it into a flag (see ``_prepare_nvjitlink_options`` and
+# ``_prepare_driver_options`` in _linker.pyx). Collapsing inputs through
+# these gates means semantically-equivalent configurations
+# (``debug=False`` vs ``None``, ``time=True`` vs ``time="path"``) hash to
+# the same cache key instead of forcing spurious misses.
+def _gate_presence(v):
+    return v is not None
+
+
+def _gate_truthy(v):
+    return bool(v)
+
+
+def _gate_is_true(v):
+    return v is True
+
+
+def _gate_tristate_bool(v):
+    return None if v is None else bool(v)
+
+
+def _gate_identity(v):
+    return v
+
+
+_LINKER_FIELD_GATES = {
+    "name": _gate_identity,
+    "arch": _gate_identity,
+    "max_register_count": _gate_identity,
+    "time": _gate_presence,  # linker emits ``-time`` iff value is not None
+    "link_time_optimization": _gate_truthy,
+    "debug": _gate_truthy,
+    "lineinfo": _gate_truthy,
+    "ftz": _gate_tristate_bool,
+    "prec_div": _gate_tristate_bool,
+    "prec_sqrt": _gate_tristate_bool,
+    "fma": _gate_tristate_bool,
+    "split_compile": _gate_identity,
+    "ptxas_options": _gate_identity,
+    "no_cache": _gate_is_true,
+}
+
+
 def _linker_option_fingerprint(options: ProgramOptions) -> list[bytes]:
-    """Stable byte fingerprint of ProgramOptions fields consumed by the Linker."""
-    return [f"{name}={getattr(options, name, None)!r}".encode() for name in _LINKER_RELEVANT_FIELDS]
+    """Stable byte fingerprint of ProgramOptions fields consumed by the Linker.
+
+    Each field is first passed through the gate the Linker itself uses so
+    that equivalent inputs (e.g. ``debug=False`` / ``None``) produce the
+    same bytes. Without this, callers hitting the same linker behavior
+    would get different cache keys and needlessly re-compile.
+    """
+    return [
+        f"{name}={_LINKER_FIELD_GATES[name](getattr(options, name, None))!r}".encode()
+        for name in _LINKER_RELEVANT_FIELDS
+    ]
 
 
 # ProgramOptions fields that map to LinkerOptions fields the cuLink (driver)
@@ -585,9 +638,11 @@ def _probe(label: str, fn):
             else:
                 # Fallback for unexpected format.
                 _update("extra_source", str(item).encode("utf-8"))
-    use_libdevice = getattr(options, "use_libdevice", None)
-    if use_libdevice is not None:
-        _update("use_libdevice", str(use_libdevice).encode("ascii"))
+    # Program_init gates ``use_libdevice`` on truthiness, not ``is not None``
+    # (see _program.pyx), so False and None produce identical ObjectCode and
+    # must hash the same way here.
+    if getattr(options, "use_libdevice", None):
+        _update("use_libdevice", b"1")
 
     # Program.compile() propagates options.name onto the returned ObjectCode,
     # so two compiles identical in everything but name produce ObjectCodes

cuda_core/tests/test_program_cache.py

@@ -340,6 +340,54 @@ def test_make_program_cache_key_ignores_name_expressions_for_non_nvrtc(code_type
     assert k_none == k_with
 
 
+@pytest.mark.parametrize(
+    "a, b",
+    [
+        # ``debug`` / ``lineinfo`` / ``link_time_optimization`` are truthy-only
+        # gates in the linker; False and None produce identical output.
+        pytest.param({"debug": False}, {"debug": None}, id="debug_false_eq_none"),
+        pytest.param({"lineinfo": False}, {"lineinfo": None}, id="lineinfo_false_eq_none"),
+        pytest.param(
+            {"link_time_optimization": False},
+            {"link_time_optimization": None},
+            id="lto_false_eq_none",
+        ),
+        # ``time`` is a presence gate: the linker emits ``-time`` for any
+        # non-None value, so True / "path" produce the same flag.
+        pytest.param({"time": True}, {"time": "timing.csv"}, id="time_true_eq_path"),
+        # ``no_cache`` has an ``is True`` gate; False and None equivalent.
+        pytest.param({"no_cache": False}, {"no_cache": None}, id="no_cache_false_eq_none"),
+    ],
+)
+def test_make_program_cache_key_ptx_linker_equivalent_options_hash_same(a, b, monkeypatch):
+    """The linker folds several PTX-relevant fields through simple gates:
+    truthy-only (``debug``, ``lineinfo``, ``link_time_optimization``),
+    presence-only (``time``), ``is True`` (``no_cache``). Semantically
+    equivalent inputs under those gates must hash to the same key."""
+    # Pin the linker probe so the only variable is the options gate.
+    from cuda.core.utils import _program_cache
+
+    monkeypatch.setattr(_program_cache, "_linker_backend_and_version", lambda: ("nvJitLink", "12030"))
+    k_a = _make_key(code=".version 7.0", code_type="ptx", options=_opts(**a))
+    k_b = _make_key(code=".version 7.0", code_type="ptx", options=_opts(**b))
+    assert k_a == k_b
+
+
+def test_make_program_cache_key_nvvm_use_libdevice_false_equals_none():
+    """Program_init gates ``use_libdevice`` on truthiness, so False and None
+    compile identically and must hash the same way."""
+    # With the NVVM probe mocked so the NVVM portion is stable.
+    from cuda.core.utils import _program_cache
+
+    # Use real probe; the key differences come only from use_libdevice here.
+    k_none = _make_key(code="abc", code_type="nvvm", target_type="ptx", options=_opts(use_libdevice=None))
+    k_false = _make_key(code="abc", code_type="nvvm", target_type="ptx", options=_opts(use_libdevice=False))
+    k_true = _make_key(code="abc", code_type="nvvm", target_type="ptx", options=_opts(use_libdevice=True))
+    assert k_none == k_false
+    assert k_true != k_none
+    _ = _program_cache  # silence unused warning
+
+
 def test_make_program_cache_key_nvvm_probe_changes_key(monkeypatch):
     """NVVM keys must reflect the NVVM toolchain identity (IR version)
     so an upgraded libNVVM does not silently reuse pre-upgrade entries."""