cuda.core: rename _resource_handles to _rt and split its C++ into _cpp/rt/ - #2837
Merged
Andy-Jost merged 6 commits intoSep 15, 2026
Merged
Conversation
Andy-Jost
added
enhancement
Contributor
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
Contributor
Author
|
/ok to test |
Contributor
|
Contributor
Author
|
/ok to test |
Andy-Jost
force-pushed
the
ajost/resource-handles-refactor
branch
from
September 14, 2026 16:40
2161c01 to
7ee9c1f
Compare
Andy-Jost
changed the title
mdboom
approved these changes
Sep 14, 2026
mdboom
left a comment
mdboom
left a comment
Contributor
There was a problem hiding this comment.
Other than the one thing (which would break my workflow, at least), LGTM.
| 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") |
Contributor
There was a problem hiding this comment.
This will break if building from anywhere but cuda_core.
Suggested change
| cpp = Path("cuda", "core", "_cpp") | |
| cpp = Path(__file__).parent / "cuda" / "core" / "_cpp" |
Contributor
Author
There was a problem hiding this comment.
I forgot to include this. I will make a follow-up PR right after this merges.
The module holds cuda.core's runtime support layer: resource handles, the
driver function-pointer table, error reporting and deferred cleanup. Rename
it to _rt and move its C++ under _cpp/rt/ in namespace cuda_core::rt. Every
function keeps its body, signature and symbol name; only the namespace
qualifier and the file names change.
- git mv _resource_handles.{pyx,pxd,pyi} to _rt.*; resource_handles.{hpp,cpp}
to _cpp/rt/rt.{hpp,cpp}; the three design notes to _cpp/rt/.
- The 53 cimporting Cython files change only their cimport line.
- Delete _CUDA_DRIVER_API_V1_NAME, a capsule-name constant nothing reads.
- Regenerate the stub (stubgen-pyx).
The dynamic symbol table of the built extension equals the old one under
s/cuda_core::/cuda_core::rt::/, and __pyx_capi__ has the same keys.
A Py_DECREF callback shaped for cuUserObjectCreate, superseded by the make_opaque_py ownership path and called from nowhere. Its four declarations go: the C++ prototype and body, the .pxd cdef and the .pyx extern declaration.
…sion's sources in parallel Two build changes the C++ split needs. Every extension now lists the headers under cuda/core/_cpp/<stem>/ as `depends`. A cimporting extension compiles against the header its .pxd names, and cythonize copies each `depends` entry into its build directory, so the copied header finds its sibling includes beside it. Listing the whole directory avoids parsing includes; every extension rebuilds when one of these headers changes, exactly as editing the one monolithic header did. setuptools compiles the sources of one extension serially and parallelizes only across extensions, so a multi-source extension becomes the critical path. build_ext now fans the per-object compile calls of every extension out to one shared thread pool of `nthreads` workers. MSVC keeps the stock path.
The monolithic header becomes: types.hpp (handle aliases, tagged values, Prepared* types, the inline as_cu/as_intptr accessors), py.hpp (the one file that includes <Python.h>: py_is_finalizing, make_py and as_py, and the prototypes that take or return PyObject*), driver_api.hpp (the p_* table and the version-gated shims), error.hpp (thread-local error state and the non-propagating reporting API), api.hpp (every other prototype, one banner per resource family), plus two umbrellas: rt.hpp, named only by _rt.pyx, and handles.hpp, named only by _rt.pxd, whose include closure is types.hpp and py.hpp. Every declaration moves verbatim; the only additions are the file boilerplate, one banner in py.hpp and `// Implemented in <file>` lines on the prototypes whose body lives outside their family source. The generator (anchored on the monolith's text) and its check mode live in the maintainer's notes; the dynamic symbol table and __pyx_capi__ of the built extension are unchanged.
The monolithic source becomes twelve translation units: one resource family per file (context, stream, event, memory, program, graph, graph_exec, texture), the driver table with its version-gated shims (driver_api.cpp), the error state and non-propagating reporting (error.cpp), and the two Python-coupled bodies (py_report.cpp, py_deferred_cleanup.cpp). Two headers hold the helpers the files share and Cython never names, in namespace cuda_core::rt::detail: context_scope.hpp (enter/restore/exit_context and the invoke_in_context templates) and internal.hpp (HandleRegistry, WarnOnFailure with the pw_* wrappers, DeallocationStream, DeferredCleanupItem and the declarations of the promoted helpers). py.hpp gains the GIL guards; error.hpp declares the thread-local `err` that error.cpp now defines. Every definition moves verbatim. Helpers that were static or in an anonymous namespace and are now called across files become external with a declaration; everything local to one file keeps its anonymous namespace. driver_api.cpp and error.cpp compile without a Python include path. Verification: the generator's check mode reproduces all 21 files from the monoliths; the dynamic symbol table gains exactly the nine promoted detail:: functions and the err object and loses nothing; __pyx_capi__ is unchanged. tests/test_rt_layout.py pins the layout rules.
DESIGN.md, GRAPH_ATTACHMENTS.md and REGISTRY_DESIGN.md moved with the code; this keeps them from misleading: the module name, the file layout, the cdef extern examples, and the heading that still named the deleted _CUDA_DRIVER_API_V1 capsule. AGENTS.md learns the directory form of _cpp/<name>/ and the new paths. One release note for the renamed private module and its shipped .pxd.
Andy-Jost
force-pushed
the
ajost/resource-handles-refactor
branch
from
September 15, 2026 18:57
7ee9c1f to
c61a5b5
Compare
Andy-Jost
changed the title
Andy-Jost
marked this pull request as ready for review
September 15, 2026 18:57
Andy-Jost
enabled auto-merge (squash)
September 15, 2026 20:45
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
cuda.core._resource_handlesholds cuda.core's runtime support layer: the resource handles, the driver function-pointer table, the GIL and context guards, the error-reporting path, deferred cleanup, the handle registry and a few version-gated driver shims. This renames it tocuda.core._rt, moves its C++ undercuda/core/_cpp/rt/in namespacecuda_core::rt, and splits the two monoliths (about 1,240 and 3,360 lines) into nine headers and twelve sources, one resource family per file, with the Python-coupled code behind a single header. Behavior does not change. One dead function and one dead constant go.Every function keeps its body, signature and symbol name; only the namespace qualifier and the file it lives in move. The
.pxdexposes the same declarations in the same order minus the dead function, and the 53 cimporting Cython files change only their cimport line. All of the C++ still compiles into the one_rtextension, so the shared state (registries, thread-local error slot, driver pointers, cleanup queue) keeps living in exactly one shared library.Layout (
cuda/core/_cpp/rt/):rt.hpp(umbrella, named only by_rt.pyx),handles.hpp(umbrella, named only by_rt.pxd; its closure istypes.hppandpy.hpp),types.hpp(handle aliases, tagged values,Prepared*types, inlineas_cu/as_intptr),api.hpp(every other prototype, one banner per family),driver_api.hpp/.cpp(thep_*table and version-gated shims),error.hpp/.cpp(thread-local error state, non-propagating reporting),py.hpp(the one file that includes<Python.h>:py_is_finalizing, the GIL guards,as_py, thePyObject*prototypes),context_scope.hppandinternal.hpp(helpers shared across files and never named from Cython, incuda_core::rt::detail),py_report.cpp,py_deferred_cleanup.cpp, andcontext.cpp,stream.cpp,event.cpp,memory.cpp,program.cpp,graph.cpp,graph_exec.cpp,texture.cpp.driver_api.cppanderror.cppcompile with no Python include path. The three design notes move with the code.Build. Every extension lists the headers under
_cpp/<stem>/asdepends, because a cimporting extension compiles against the copy ofhandles.hppthat cythonize places in its build directory, and the copy needs its siblings beside it.build_extnow compiles the sources of every extension through one shared thread pool (setuptools compiles an extension's sources serially and parallelizes only across extensions), so the twelve translation units add no wall-clock time.Commits. The series is built to be reviewed step by step: rename with no code motion; remove the dead
py_object_user_object_destroy; build hooks; header split; source split (withtests/test_rt_layout.py); docs.Verification.
// Implemented inlines, the few new declarations) plus verbatim ranges; its check mode regenerates from the pre-split revision and compares with the files in the tree. After cuda.core: define the error handling policy and report failures that cannot be raised #2759 merged, the series was regenerated on main the same way rather than merged by hand, and the result differs from the previously approved head by exactly cuda.core: define the error handling policy and report failures that cannot be raised #2759's final changes carried into the split files._rtequals the old module's unders/cuda_core::/cuda_core::rt::/, minus the removed function, plus exactly the ten helpers promoted from anonymous namespaces tocuda_core::rt::detailand theerrobject.__pyx_capi__has the same 104 keys with the same signatures.test_rt_layout.pypins the seam rules:<Python.h>only inpy.hpp, bare sibling includes that exist, umbrellas named only by their Cython file, the consumer closure with nothing that has storage, and no.pxd-declared function called by its own name inside_rt.pyx.system/test_system_device.py::test_device_cpu_affinity, comes from NVML reporting an empty CPU set for the GPUs of that machine and does not involve this code. (An environment pairing 13.1 headers with cuda-bindings 13.2 fails the 14 copy-options tests on this branch and on main alike; that is cuda-core: require a cuda-bindings version floor at build and run time #2783's "guards disable working features", not this change.) cu12 and Windows through CI.Checklist
🤖 Generated with Claude Code