Various handle-related changes and improvements

[leofang]

Close #370. Close #433.

• Ensure Program/Linker have consistent .backend and .handle
  • This allows us to add e.g. CXXProgram, PTXProgram, ... in the future without breaking changes (Expose ObjectCode as public API + prune unnecessary input arguments #435 (comment))
• Add get_cuda_native_handle() to fetch the underlying CUDA C object from the corresponding cuda.bindings Python-layer object
  • Recall that for all generated bindings there are 3 layers: Python, Cython, and internal. This refers to the Python layer. The Cython layer provides the C type information (i.e. think of it as a CUDA header)
  • Steps:
    1. Take the Python wrapper object from <some_cuda_core_object>.handle
    2. Pass it to get_cuda_native_handle(), and the underlying C object is returned (no refcount or lifetime management)
  • Since cuda.core is not yet cythonized, this is currently the best solution for Python/Cython/C++ interoperability. Once we lower to Cython we can also apply a similar treatment to all cuda.core objects.
    • This includes implementing ref counting via shared_ptr or other C++ machinery to keep track of lifetime across C++ and Python. We are not there yet.
    • Additional work on cuda.bindings is also needed (Turn all cdef class objects in the Python layer to cdef public class #464)
  • For reviewers of this part: Please focus on these two files (the rest of Cython-related files are direct copy/paste from our existing cuda.bindings infrastructure):
    • tests/cython/test_get_cuda_native_handle.pyx
    • cuda/core/experimental/include/utility.hpp
• some minor doc build fixes

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[leofang]

/ok to test

[leofang]

@vzhurba01 do you recall what prompted this change when updating to 12.8?

[rwgk]

We're using a private member? Do we own the code with the private member?

[leofang]

Yes we own everything, they are autogen'd, for example for CUstream:

cuda-python/cuda_bindings/cuda/bindings/driver.pxd.in

Lines 185 to 197 in 02a4178

	cdef class CUstream:
	"""
	CUDA stream
	Methods
	-------
	getPtr()
	Get memory address of class instance
	"""
	cdef cydriver.CUstream _pvt_val
	cdef cydriver.CUstream* _pvt_ptr

hence I feel SFINAE over all possibilities is OK. I think if we accidentally change the codegen in the future, the added Cython test should be able to catch it.

[leofang]

/ok to test

[leofang]

/ok to test

[leofang]

/ok to test

[leofang]

/ok to test

[rwgk]

I only have a few minor comments. I didn't see anything troubling, except the raise vs pass question maybe.

[rwgk]

We're using a private member? Do we own the code with the private member?

[rwgk]

I only have a few minor comments. I didn't see anything troubling, except the raise vs pass question maybe.

Oh wait, did the except ImportError: raise disappear in the meantime? Please disregard.

[rwgk]

Here it is, I accidentally lost my original comment.

Did you mean to write pass here?

Also, it's safer to make the try-except scope as narrow as possible, e.g. (untested):

    try:
        # For each callable in `mod` with name `test_*`,
        # wrap the callable in a plain Python function
        # and set the result as an attribute of this module.
        mod = importlib.import_module(mod)
    except ImportError:
        pass
    else:
        for name in dir(mod):
            item = getattr(mod, name)
            if callable(item) and name.startswith("test_"):
                item = py_func(item)
                setattr(sys.modules[__name__], name, item)

If there is any tooling that might import this file for analysis: Moving the for loop into a function and using if __name__ == "__main__": could guard against surprises.

[leofang]

This file is copied/pasted from cuda-bindings. I think Vlad (or @shwina? 🙂) was the original author:
https://shwina.github.io/cython-testing/

Did you mean to write pass here?

I suspect the answer was yes (based on Ashwin's blog post) but perhaps it caused some issues, so it was changed to raise? I can see that this is a cheap way to ensure the listed modules must exist and get tested. But then the whole try-except can be removed (or refactored). Perhaps @vzhurba01 can confirm the intention?

In any case, since this is a copy/paste let's change both files in a separate PR.

[leofang]

/ok to test

[leofang]

Note: This approach left a bug uncaught (fixed in commit 37a6850): Ideally, we want to have a cmdline functionality like PyBind11 that returns the header path, something like python -m cuda.core --include-path. Here, we use the header from the local clone of this repo (hence using $SCRIPTPATH) instead of the installed cuda.core package, meaning we do not check if the header is actually packaged (and it was not before the fix). However, I think the said functionality needs to be done in a separate PR...

[leofang]

Example that I added to cuQuantum: https://docs.nvidia.com/cuda/cuquantum/latest/python/api/cuquantum.html#command-line-support

[leofang]

/ok to test

[rwgk]

/ok to test

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.