Merge pull request #573 from carterbox/dching/note-CUObject-c-pointer

DOC: Add admonition to docstrings for cuda.core handle properties

Author: leofang

cuda_core/cuda/core/experimental/_event.py

@@ -164,5 +164,11 @@ def is_done(self) -> bool:
 
     @property
     def handle(self) -> cuda.bindings.driver.CUevent:
-        """Return the underlying CUevent object."""
+        """Return the underlying CUevent object.
+
+        .. caution::
+
+            This handle is a Python object. To get the memory address of the underlying C
+            handle, call ``int(Event.handle)``.
+        """
         return self._mnff.handle

cuda_core/cuda/core/experimental/_linker.py

@@ -503,6 +503,11 @@ def handle(self) -> LinkerHandleT:
         .. note::
 
            The type of the returned object depends on the backend.
+
+        .. caution::
+
+            This handle is a Python object. To get the memory address of the underlying C
+            handle, call ``int(Linker.handle)``.
         """
         return self._mnff.handle
 

cuda_core/cuda/core/experimental/_memory.py

@@ -6,7 +6,7 @@
 
 import abc
 import weakref
-from typing import Optional, Tuple, TypeVar
+from typing import Optional, Tuple, TypeVar, Union
 
 from cuda.core.experimental._dlpack import DLDeviceType, make_py_capsule
 from cuda.core.experimental._stream import default_stream
@@ -18,6 +18,9 @@
 # TODO: define a memory property mixin class and make Buffer and
 # MemoryResource both inherit from it
 
+DevicePointerT = Union[driver.CUdeviceptr, int, None]
+"""A type union of `Cudeviceptr`, `int` and `None` for hinting Buffer.handle."""
+
 
 class Buffer:
     """Represent a handle to allocated memory.
@@ -81,8 +84,14 @@ def close(self, stream=None):
         self._mnff.close(stream)
 
     @property
-    def handle(self):
-        """Return the buffer handle object."""
+    def handle(self) -> DevicePointerT:
+        """Return the buffer handle object.
+
+        .. caution::
+
+            This handle is a Python object. To get the memory address of the underlying C
+            handle, call ``int(Buffer.handle)``.
+        """
         return self._mnff.ptr
 
     @property

cuda_core/cuda/core/experimental/_module.py

@@ -354,5 +354,11 @@ def code(self) -> CodeTypeT:
     @property
     @precondition(_lazy_load_module)
     def handle(self):
-        """Return the underlying handle object."""
+        """Return the underlying handle object.
+
+        .. caution::
+
+            This handle is a Python object. To get the memory address of the underlying C
+            handle, call ``int(ObjectCode.handle)``.
+        """
         return self._handle

cuda_core/cuda/core/experimental/_program.py

@@ -524,5 +524,10 @@ def handle(self) -> ProgramHandleT:
         .. note::
 
            The type of the returned object depends on the backend.
+
+        .. caution::
+
+            This handle is a Python object. To get the memory address of the underlying C
+            handle, call ``int(Program.handle)``.
         """
         return self._mnff.handle

cuda_core/cuda/core/experimental/_stream.py

@@ -189,7 +189,13 @@ def __cuda_stream__(self) -> Tuple[int, int]:
 
     @property
     def handle(self) -> cuda.bindings.driver.CUstream:
-        """Return the underlying ``CUstream`` object."""
+        """Return the underlying ``CUstream`` object.
+
+        .. caution::
+
+            This handle is a Python object. To get the memory address of the underlying C
+            handle, call ``int(Stream.handle)``.
+        """
         return self._mnff.handle
 
     @property