cuda.core: rename _resource_handles to _rt and split its C++ into _cpp/rt/ [stacked on #2759, #2799]

.gitignore

@@ -15,6 +15,7 @@ __pycache__/
 !*_impl.cpp
 !cuda_bindings/cuda/bindings/_lib/param_packer.cpp
 !cuda_bindings/cuda/bindings/_bindings/loader.cpp
+!cuda_core/cuda/core/_cpp/**/*.cpp
 cache_driver
 cache_runtime
 cache_nvrtc

ci/tools/merge_cuda_core_wheels.py

@@ -133,9 +133,11 @@ def merge_wheels(wheels: list[Path], output_dir: Path, show_wheel_contents: bool
         # Copy version-specific directories from each wheel into versioned subdirectories
         base_dir = Path("cuda") / "core"
 
+        versioned_dirs = set()
         for i, wheel_dir in enumerate(extracted_wheels):
             cuda_version = wheels[i].name.split(".cu")[1].split(".")[0]
             versioned_dir = base_wheel / base_dir / f"cu{cuda_version}"
+            versioned_dirs.add(versioned_dir.name)
 
             # Copy entire directory tree from source wheel to versioned directory
             print(f"  Copying {wheel_dir / base_dir} to {versioned_dir}", file=sys.stderr)
@@ -145,25 +147,17 @@ def merge_wheels(wheels: list[Path], output_dir: Path, show_wheel_contents: bool
             os.truncate(versioned_dir / "__init__.py", 0)
 
         print("\n=== Removing files from cuda/core/ directory ===", file=sys.stderr)
-        items_to_keep = (
-            "__init__.py",
-            "_version.py",
-            "_include",
-            "_cpp",  # Headers for Cython development
-            "cu12",
-            "cu13",
-        )
-        # _resource_handles is shared (not CUDA-version-specific) and must stay
-        # at top level. It's imported early in __init__.py before versioned code.
-        items_to_keep_prefix = ("_resource_handles",)
+        # Only what cuda/core/__init__.py uses before it rewrites __path__ to the
+        # versioned subpackage stays at top level: it imports _version, then
+        # redirects every later import into the versioned tree. Anything else
+        # left at top level is a dead copy that nothing imports.
+        items_to_keep = {"__init__.py", "_version.py", *versioned_dirs}
         all_items = os.scandir(base_wheel / base_dir)
         removed_count = 0
         for f in all_items:
             f_abspath = f.path
             if f.name in items_to_keep:
                 continue
-            if any(f.name.startswith(prefix) for prefix in items_to_keep_prefix):
-                continue
             if f.is_dir():
                 print(f"  Removing directory: {f.name}", file=sys.stderr)
                 shutil.rmtree(f_abspath)
@@ -172,6 +166,11 @@ def merge_wheels(wheels: list[Path], output_dir: Path, show_wheel_contents: bool
                 os.remove(f_abspath)
             removed_count += 1
         print(f"Removed {removed_count} items from cuda/core/ directory", file=sys.stderr)
+        remaining = {entry.name for entry in os.scandir(base_wheel / base_dir)}
+        if remaining != items_to_keep:
+            raise RuntimeError(
+                f"unexpected top level under cuda/core/: {sorted(remaining)} (expected {sorted(items_to_keep)})"
+            )
 
         # Repack the merged wheel
         output_dir.mkdir(parents=True, exist_ok=True)

ci/tools/tests/test_compute_ci_plan.py

@@ -113,7 +113,7 @@ def test_ignored_paths_select_no_work(self) -> None:
             "cuda_core/tests/fixtures/pixi.toml",
             "benchmarks/cuda_bindings/pixi.toml",
             "benchmarks/cuda_bindings/AGENTS.md",
-            "cuda_core/cuda/core/_cpp/DESIGN.md",
+            "cuda_core/cuda/core/_cpp/rt/DESIGN.md",
             "cuda_bindings/README.md",
             "cuda_core/README.md",
             "new-area/pixi.toml",

cuda_core/AGENTS.md

@@ -19,8 +19,9 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
   - system-level APIs: `cuda/core/system/`
   - compile/link path: `_program.pyx`, `_linker.pyx`, `_module.pyx`
   - execution path: `_launcher.pyx`, `_launch_config.pyx`, `_stream.pyx`
-- **C++ helpers**: module-specific C++ implementations live under
-  `cuda/core/_cpp/`.
+- **C++ helpers**: module-specific C++ lives under `cuda/core/_cpp/`, either as
+  one `_cpp/<name>.cpp` or as a directory `_cpp/<name>/` whose sources all
+  compile into the `_<name>` extension (`_cpp/rt/` for `_rt`).
 - **Build backend**: `build_hooks.py` handles Cython extension setup and build
   dependency wiring.
 
@@ -90,7 +91,7 @@ and agents should flag violations.
   objects that are not meant to be shared (e.g., the thread-local `Device`) do not
   need such guards (see #2321). Reference-count integrity is guaranteed; cache
   value-identity/idempotency is not.
-- **Entry points assume the GIL is held**: the helpers in `_cpp/resource_handles.*`
+- **Entry points assume the GIL is held**: the helpers in `_cpp/rt/`
   are called from Cython with the GIL held and do not re-acquire it. Driver and
   destructor callbacks run at arbitrary times, so they take the GIL (`with gil`)
   and probe for interpreter shutdown before touching Python objects.
@@ -101,6 +102,66 @@ and agents should flag violations.
   (kernel arguments, memcpy/memset operands, `dst_owner`/`src_owner`, and
   host-callback closures) inherit this contract.
 
+## Failure handling
+
+The user-facing contract lives in `docs/source/error_handling.rst`; the rules
+below are for contributors. Reviewers and agents should flag violations.
+
+- **Raise by default**: any failure on a path where an exception can propagate
+  raises. Driver statuses go through `HANDLE_RETURN` (Cython) or are returned as
+  `CUresult` from the C++ handle layer and then `HANDLE_RETURN`ed; never
+  replace a `CUresult` with a generic `RuntimeError`, and drain
+  `get_last_error()` immediately after a handle constructor returns empty so a
+  stale status cannot be misattributed later.
+- **Guarantees**: a call that creates a resource must create nothing when it
+  raises (undo the creation if a later step fails). Every call except
+  `Device.set_current` must leave the calling thread's current context as it
+  found it. Do not hand-roll `cuCtxPush/Pop/SetCurrent` sequences in Cython; use
+  the handle layer's scoped-context helpers (`invoke_in_context`,
+  `invoke_in_context_or_undo`, `cleanup_in_context`, `context_get_device`,
+  `graph_node_set_params`) so the failure handling exists in one place.
+- **Publish before you raise**: when a driver mutation has succeeded and a later
+  step can still fail, commit whatever keeps that mutation memory-safe (for
+  example the graph attachment that retains a node's new owners) before raising
+  the later error. Rolling back the retention of a live mutation creates a
+  dangling reference. When ownership cannot be established, retain the
+  resources anyway (leak) rather than release them; a leak is always preferred
+  to a use-after-free.
+- **Non-propagating paths never raise and never discard a status**: shared_ptr
+  deleters, `__dealloc__` and CUDA callbacks report through one channel, `report_cuda_error()` / `report_message()` in C++ (the
+  `pw_*` wrappers) or `warnings.warn(..., CUDAWarning)` in Cython and Python,
+  which emits `cuda.core.CUDAWarning`. No `print(file=sys.stderr)` and no
+  `fprintf` outside that helper. `CUDA_ERROR_DEINITIALIZED` is filtered by the
+  helper because it means the driver is shutting down.
+- **Rollback failure**: the original exception propagates; the failed rollback
+  is attached to it with `note_or_report_cuda_error()` (a PEP 678 note on
+  Python 3.11+, reported out-of-band on 3.10), or chained with
+  `raise ... from` when a second exception must be raised. Catching everything
+  (bare `except:` or `except BaseException:`) is acceptable only for
+  rollback-then-`raise` blocks, where the rollback must also run for
+  `KeyboardInterrupt`.
+- **Finalization**: once `py_is_finalizing()` is true, do no Python work from
+  destructors or callbacks and accept the leak (see
+  `_cpp/rt/py.hpp` and `_cpp/rt/GRAPH_ATTACHMENTS.md`).
+- **Aborting**: `std::abort` (or any process termination) is reserved for an
+  internal invariant violation where continuing could corrupt memory or produce
+  silently wrong results *and* no leak-based fallback exists. A failed CUDA
+  call, including a failed context restoration, never qualifies: raise or
+  report instead. There is currently no such path; if one is ever needed it
+  must go through a single helper that writes a diagnostic (call, CUDA error,
+  invariant, "please report") and a Python traceback of all threads to stderr
+  before aborting (as `faulthandler` does, via the GIL-free
+  `_Py_DumpTracebackThreads`; no Python-object work), must never trigger
+  during interpreter finalization or for driver-shutdown errors, and must be
+  called out in the docs and release notes. An *implicit* abort (an exception
+  escaping a `noexcept` function or a deleter, including `std::bad_alloc` from
+  an allocation inside `noexcept` code) is a bug (#1489, #2417), not a policy
+  choice: `noexcept` helpers must not allocate, or must catch what they call.
+- **Testing**: inject restoration failures with
+  `cuda.core._rt._set_context_restore_fault_for_testing`; assert
+  reports with `pytest.warns(CUDAWarning)` or `warnings.catch_warnings`, never
+  by matching stderr text.
+
 ## API design guidelines
 
 These are some API design guidelines we try to follow when adding new APIs to

cuda_core/build_hooks.py

@@ -183,6 +183,45 @@ def _relativize_extension_sources(extensions) -> None:
         ]
 
 
+def _extension_sources(mod_name):
+    """The module's .pyx plus its C++, if any: every .cpp under
+    cuda/core/_cpp/<stem>/, or the single legacy file cuda/core/_cpp/<stem>.cpp.
+    Example: _tensor_map.pyx compiles _cpp/tensor_map.cpp."""
+    sources = [f"cuda/core/{mod_name}.pyx"]
+    cpp_stem = Path("cuda", "core", "_cpp", mod_name.lstrip("_"))
+    if cpp_stem.is_dir():
+        cpp_sources = sorted(str(path) for path in cpp_stem.rglob("*.cpp"))
+        if not cpp_sources:
+            raise RuntimeError(f"{cpp_stem}/ exists but contains no .cpp files")
+        sources.extend(cpp_sources)
+    elif cpp_stem.with_suffix(".cpp").is_file():
+        sources.append(str(cpp_stem.with_suffix(".cpp")))
+    return sources
+
+
+def _extension_depends():
+    """Headers whose edits must rebuild an extension: every header under a
+    directory-form module's cuda/core/_cpp/<stem>/ (a single-file module has
+    none).
+
+    The same list serves every extension. A module that cimports a
+    directory-form module compiles against the header its .pxd names, and
+    cythonize copies each `depends` entry into its build directory before
+    compiling, so the copied header finds its sibling includes beside it
+    (quoted includes resolve next to the copy, not in the source tree).
+    Listing the whole directory keeps the rule free of include parsing; the
+    cost is that every extension rebuilds when any of these headers changes,
+    exactly as editing the one monolithic header did before the split."""
+    cpp = Path("cuda", "core", "_cpp")
+    return sorted(
+        str(path)
+        for module_dir in cpp.iterdir()
+        if module_dir.is_dir()
+        for path in module_dir.rglob("*")
+        if path.suffix in (".h", ".hpp")
+    )
+
+
 def _build_cuda_core(debug=False):
     # Customizing the build hooks is needed because we must defer cythonization until cuda-bindings,
     # now a required build-time dependency that's dynamically installed via the other hook below,
@@ -227,18 +266,6 @@ def module_names():
                 continue
             yield mod
 
-    def get_sources(mod_name):
-        """Get source files for a module, including any .cpp files."""
-        sources = [f"cuda/core/{mod_name}.pyx"]
-
-        # Add module-specific .cpp file from _cpp/ directory if it exists
-        # Example: _resource_handles.pyx finds _cpp/resource_handles.cpp.
-        cpp_file = f"cuda/core/_cpp/{mod_name.lstrip('_')}.cpp"
-        if os.path.exists(cpp_file):
-            sources.append(cpp_file)
-
-        return sources
-
     all_include_dirs = [os.path.join(cuda_path, "include")]
     extra_compile_args = []
     extra_link_args = []
@@ -261,10 +288,12 @@ def get_sources(mod_name):
         # related to free-threading builds.
         extra_compile_args += ["-DCYTHON_TRACE_NOGIL=1", "-DCYTHON_USE_SYS_MONITORING=0"]
 
+    depends = _extension_depends()
     ext_modules = tuple(
         Extension(
             f"cuda.core.{mod.replace(os.path.sep, '.')}",
-            sources=get_sources(mod),
+            sources=_extension_sources(mod),
+            depends=depends,
             include_dirs=[
                 "cuda/core/_include",
                 "cuda/core/_cpp",
@@ -295,6 +324,10 @@ def get_sources(mod_name):
         # CUDA_PYTHON_COVERAGE deliberately generates in-tree so the sources can
         # be packaged; every other build gets its own per-configuration cache,
         # anchored alongside the stamp so both resolve the same from any cwd.
+        # Cython also copies each extension's extern headers and `depends` under
+        # this directory and compiles against the copies. Copies are refreshed by
+        # mtime and never deleted, so remove build/ after renaming or deleting a
+        # header under _cpp/.
         build_dir="." if COMPILE_FOR_COVERAGE else str(_BUILD_DIR / "cython" / f"cu{cuda_major}"),
         nthreads=nthreads,
         compiler_directives=compiler_directives,

cuda_core/cuda/core/__init__.py

@@ -102,8 +102,10 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
 from cuda.core._stream import __all__ as _stream_all
 from cuda.core._tensor_map import *
 from cuda.core._tensor_map import __all__ as _tensor_map_all
+from cuda.core._utils.cuda_utils import CUDAWarning
 
 __all__ = [
+    "CUDAWarning",
     *_context_all,
     *_device_all,
     *_device_resources_all,

cuda_core/cuda/core/_context.pxd

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from cuda.core._resource_handles cimport ContextHandle, GreenCtxHandle
+from cuda.core._rt cimport ContextHandle, GreenCtxHandle
 
 cdef class Context:
     """Cython declaration for Context class.

cuda_core/cuda/core/_context.pyx

@@ -13,7 +13,7 @@ import cython
 from cuda.bindings cimport cydriver
 from cuda.core._device_resources cimport DeviceResources, SMResource, WorkqueueResource
 from cuda.core._device_resources import SMResource, WorkqueueResource
-from cuda.core._resource_handles cimport (
+from cuda.core._rt cimport (
     ContextHandle,
     GreenCtxHandle,
     as_cu,