Merge remote-tracking branch 'upstream/main' into cuda.core.system-events

Author: mdboom

.gitattributes

@@ -6,6 +6,9 @@ cuda/_version.py export-subst
 # we do not own any headers checked in, don't touch them
 *.h binary
 *.hpp binary
+# Exception: headers we own (cuda_core C++ implementation)
+cuda_core/cuda/core/_cpp/*.h -binary text diff
+cuda_core/cuda/core/_cpp/*.hpp -binary text diff
 # git should not convert line endings in PNG files
 *.png binary
 *.svg binary

.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 .pytest_cache/
 .benchmarks/
 *.cpp
+!*_impl.cpp
 !cuda_bindings/cuda/bindings/_lib/param_packer.cpp
 !cuda_bindings/cuda/bindings/_bindings/loader.cpp
 cache_driver

ci/tools/merge_cuda_core_wheels.py

@@ -150,15 +150,21 @@ def merge_wheels(wheels: List[Path], output_dir: Path, show_wheel_contents: bool
             "__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",)
         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)

cuda_bindings/docs/source/conf.py

@@ -53,6 +53,12 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Include object entries (methods, attributes, etc.) in the table of contents
+# This enables the "On This Page" sidebar to show class methods and properties
+# Requires Sphinx 5.1+
+toc_object_entries = True
+toc_object_entries_show_parents = "domain"
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -69,6 +75,10 @@
         "version-switcher",
         "navbar-nav",
     ],
+    # Use custom secondary sidebar that includes autodoc entries
+    "secondary_sidebar_items": ["page-toc"],
+    # Show more TOC levels by default
+    "show_toc_level": 3,
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):

cuda_bindings/tests/nvml/test_nvlink.py

@@ -11,14 +11,14 @@ def test_nvlink_get_link_count(all_devices):
     """
     for device in all_devices:
         fields = nvml.FieldValue(1)
-        fields[0].field_id = nvml.FI.DEV_NVLINK_LINK_COUNT
+        fields[0].field_id = nvml.FieldId.DEV_NVLINK_LINK_COUNT
         value = nvml.device_get_field_values(device, fields)[0]
         assert value.nvml_return == nvml.Return.SUCCESS or value.nvml_return == nvml.Return.ERROR_NOT_SUPPORTED, (
             f"Unexpected return {value.nvml_return} for link count field query"
         )
 
         # Use the alternative argument to device_get_field_values
-        value = nvml.device_get_field_values(device, [nvml.FI.DEV_NVLINK_LINK_COUNT])[0]
+        value = nvml.device_get_field_values(device, [nvml.FieldId.DEV_NVLINK_LINK_COUNT])[0]
         assert value.nvml_return == nvml.Return.SUCCESS or value.nvml_return == nvml.Return.ERROR_NOT_SUPPORTED, (
             f"Unexpected return {value.nvml_return} for link count field query"
         )

cuda_core/MANIFEST.in

@@ -3,3 +3,4 @@
 # SPDX-License-Identifier: Apache-2.0
 
 recursive-include cuda/core *.pyx *.pxd
+recursive-include cuda/core/_cpp *.cpp *.hpp

cuda_core/build_hooks.py

@@ -100,6 +100,17 @@ def module_names():
         for filename in glob.glob(f"{root_path}/**/*.pyx", recursive=True):
             yield filename[len(root_path) : -4]
 
+    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
+        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 = list(os.path.join(root, "include") for root in _get_cuda_paths())
     extra_compile_args = []
     if COMPILE_FOR_COVERAGE:
@@ -110,8 +121,12 @@ def module_names():
     ext_modules = tuple(
         Extension(
             f"cuda.core.{mod.replace(os.path.sep, '.')}",
-            sources=[f"cuda/core/{mod}.pyx"],
-            include_dirs=all_include_dirs,
+            sources=get_sources(mod),
+            include_dirs=[
+                "cuda/core/_include",
+                "cuda/core/_cpp",
+            ]
+            + all_include_dirs,
             language="c++",
             extra_compile_args=extra_compile_args,
         )

cuda_core/cuda/core/__init__.py

@@ -15,6 +15,15 @@
 
 import importlib
 
+# The _resource_handles module exports a PyCapsule dispatch table that other
+# extension modules access via PyCapsule_Import. We import it here to ensure
+# it's loaded before other modules try to use it.
+#
+# We use importlib.import_module with the full path to avoid triggering
+# circular import issues that can occur with relative imports during
+# package initialization.
+_resource_handles = importlib.import_module("cuda.core._resource_handles")
+
 subdir = f"cu{cuda_major}"
 try:
     versioned_mod = importlib.import_module(f".{subdir}", __package__)

cuda_core/cuda/core/_context.pxd

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from cuda.core._resource_handles cimport ContextHandle
+
+cdef class Context:
+    """Cython declaration for Context class.
+
+    This class provides access to CUDA contexts. Context objects cannot be
+    instantiated directly - use factory methods or Device/Stream APIs.
+    """
+
+    cdef:
+        ContextHandle _h_context
+        int _device_id
+
+    @staticmethod
+    cdef Context _from_handle(type cls, ContextHandle h_context, int device_id)

cuda_core/cuda/core/_context.pyx

@@ -4,35 +4,55 @@
 
 from dataclasses import dataclass
 
-from cuda.core._utils.cuda_utils import driver
+from cuda.core._resource_handles cimport (
+    ContextHandle,
+    as_intptr,
+    as_py,
+)
 
 
-@dataclass
-class ContextOptions:
-    pass  # TODO
+__all__ = ['Context', 'ContextOptions']
 
 
 cdef class Context:
+    """CUDA context wrapper.
 
-    cdef:
-        readonly object _handle
-        int _device_id
+    Context objects represent CUDA contexts and cannot be instantiated directly.
+    Use Device or Stream APIs to obtain context objects.
+    """
 
     def __init__(self, *args, **kwargs):
         raise RuntimeError("Context objects cannot be instantiated directly. Please use Device or Stream APIs.")
 
-    @classmethod
-    def _from_ctx(cls, handle: driver.CUcontext, int device_id):
-        cdef Context ctx = Context.__new__(Context)
-        ctx._handle = handle
+    @staticmethod
+    cdef Context _from_handle(type cls, ContextHandle h_context, int device_id):
+        """Create Context from existing ContextHandle (cdef-only factory)."""
+        cdef Context ctx = cls.__new__(cls)
+        ctx._h_context = h_context
         ctx._device_id = device_id
         return ctx
 
+    @property
+    def handle(self):
+        """Return the underlying CUcontext handle."""
+        if self._h_context.get() == NULL:
+            return None
+        return as_py(self._h_context)
+
     def __eq__(self, other):
         if not isinstance(other, Context):
             return NotImplemented
         cdef Context _other = <Context>other
-        return int(self._handle) == int(_other._handle)
+        return as_intptr(self._h_context) == as_intptr(_other._h_context)
 
     def __hash__(self) -> int:
-        return hash(int(self._handle))
+        return hash((type(self), as_intptr(self._h_context)))
+
+
+@dataclass
+class ContextOptions:
+    """Options for context creation.
+
+    Currently unused, reserved for future use.
+    """
+    pass  # TODO