C-api functions for memory/tensor objects(#740)

* Added more public API methods for _Memory object

* changed test to reflect change in public API function name change

* Added Memory C-API functions to dpctl_capi.h

Renamed functions to avoid name clashes for get_queue_ref/get_context_ref
defined for different signatures. (C-API requires names to be different).

Adjsuted tests to reflect changes in C-API names

* Renamed Python C-API functions to ObjectName_CamelCasedFunctionName

* Renamed usm_ndarray's C-API functions as UsmNDArray_*

* dpctl_capi imports tensor submodule as well as part of importing dpctl

* Added docstring as per PR feedback

* populated docstrings of C-API functions of usmarray

Author: oleksandr-pavlyk

dpctl/_sycl_context.pyx

@@ -480,15 +480,15 @@ cdef class SyclContext(_SyclContext):
             &_context_capsule_deleter
         )
 
-cdef api DPCTLSyclContextRef get_context_ref(SyclContext ctx):
+cdef api DPCTLSyclContextRef SyclContext_GetContextRef(SyclContext ctx):
     """
     C-API function to get opaque context reference from
     :class:`dpctl.SyclContext` instance.
     """
     return ctx.get_context_ref()
 
 
-cdef api SyclContext make_SyclContext(DPCTLSyclContextRef CRef):
+cdef api SyclContext SyclContext_Make(DPCTLSyclContextRef CRef):
     """
     C-API function to create :class:`dpctl.SyclContext` instance
     from the given opaque context reference.

dpctl/_sycl_device.pyx

@@ -1130,15 +1130,15 @@ cdef class SyclDevice(_SyclDevice):
                 else:
                     return str(relId)
 
-cdef api DPCTLSyclDeviceRef get_device_ref(SyclDevice dev):
+cdef api DPCTLSyclDeviceRef SyclDevice_GetDeviceRef(SyclDevice dev):
     """
     C-API function to get opaque device reference from
     :class:`dpctl.SyclDevice` instance.
     """
     return dev.get_device_ref()
 
 
-cdef api SyclDevice make_SyclDevice(DPCTLSyclDeviceRef DRef):
+cdef api SyclDevice SyclDevice_Make(DPCTLSyclDeviceRef DRef):
     """
     C-API function to create :class:`dpctl.SyclDevice` instance
     from the given opaque device reference.

dpctl/_sycl_event.pyx

@@ -57,14 +57,14 @@ __all__ = [
 _logger = logging.getLogger(__name__)
 
 
-cdef api DPCTLSyclEventRef get_event_ref(SyclEvent ev):
+cdef api DPCTLSyclEventRef SyclEvent_GetEventRef(SyclEvent ev):
     """ C-API function to access opaque event reference from
     Python object of type :class:`dpctl.SyclEvent`.
     """
     return ev.get_event_ref()
 
 
-cdef api SyclEvent make_SyclEvent(DPCTLSyclEventRef ERef):
+cdef api SyclEvent SyclEvent_Make(DPCTLSyclEventRef ERef):
     """
     C-API function to create :class:`dpctl.SyclEvent`
     instance from opaque sycl event reference.

dpctl/_sycl_queue.pyx

@@ -1001,15 +1001,15 @@ cdef class SyclQueue(_SyclQueue):
         self.sycl_device.print_device_info()
 
 
-cdef api DPCTLSyclQueueRef get_queue_ref(SyclQueue q):
+cdef api DPCTLSyclQueueRef SyclQueue_GetQueueRef(SyclQueue q):
     """
     C-API function to get opaque queue reference from
     :class:`dpctl.SyclQueue` instance.
     """
     return q.get_queue_ref()
 
 
-cdef api SyclQueue make_SyclQueue(DPCTLSyclQueueRef QRef):
+cdef api SyclQueue SyclQueue_Make(DPCTLSyclQueueRef QRef):
     """
     C-API function to create :class:`dpctl.SyclQueue` instance
     from the given opaque queue reference.

dpctl/apis/include/dpctl4pybind11.hpp

@@ -49,8 +49,8 @@ template <> struct type_caster<sycl::queue>
     {
         PyObject *source = src.ptr();
         if (PyObject_TypeCheck(source, &PySyclQueueType)) {
-            DPCTLSyclQueueRef QRef =
-                get_queue_ref(reinterpret_cast<PySyclQueueObject *>(source));
+            DPCTLSyclQueueRef QRef = SyclQueue_GetQueueRef(
+                reinterpret_cast<PySyclQueueObject *>(source));
             sycl::queue *q = reinterpret_cast<sycl::queue *>(QRef);
             value = *q;
             return true;
@@ -63,7 +63,7 @@ template <> struct type_caster<sycl::queue>
 
     static handle cast(sycl::queue src, return_value_policy, handle)
     {
-        auto tmp = make_SyclQueue(reinterpret_cast<DPCTLSyclQueueRef>(&src));
+        auto tmp = SyclQueue_Make(reinterpret_cast<DPCTLSyclQueueRef>(&src));
         return handle(reinterpret_cast<PyObject *>(tmp));
     }
 };
@@ -87,8 +87,8 @@ template <> struct type_caster<sycl::device>
     {
         PyObject *source = src.ptr();
         if (PyObject_TypeCheck(source, &PySyclDeviceType)) {
-            DPCTLSyclDeviceRef DRef =
-                get_device_ref(reinterpret_cast<PySyclDeviceObject *>(source));
+            DPCTLSyclDeviceRef DRef = SyclDevice_GetDeviceRef(
+                reinterpret_cast<PySyclDeviceObject *>(source));
             sycl::device *d = reinterpret_cast<sycl::device *>(DRef);
             value = *d;
             return true;
@@ -101,7 +101,7 @@ template <> struct type_caster<sycl::device>
 
     static handle cast(sycl::device src, return_value_policy, handle)
     {
-        auto tmp = make_SyclDevice(reinterpret_cast<DPCTLSyclDeviceRef>(&src));
+        auto tmp = SyclDevice_Make(reinterpret_cast<DPCTLSyclDeviceRef>(&src));
         return handle(reinterpret_cast<PyObject *>(tmp));
     }
 };
@@ -125,7 +125,7 @@ template <> struct type_caster<sycl::context>
     {
         PyObject *source = src.ptr();
         if (PyObject_TypeCheck(source, &PySyclContextType)) {
-            DPCTLSyclContextRef CRef = get_context_ref(
+            DPCTLSyclContextRef CRef = SyclContext_GetContextRef(
                 reinterpret_cast<PySyclContextObject *>(source));
             sycl::context *ctx = reinterpret_cast<sycl::context *>(CRef);
             value = *ctx;
@@ -140,7 +140,7 @@ template <> struct type_caster<sycl::context>
     static handle cast(sycl::context src, return_value_policy, handle)
     {
         auto tmp =
-            make_SyclContext(reinterpret_cast<DPCTLSyclContextRef>(&src));
+            SyclContext_Make(reinterpret_cast<DPCTLSyclContextRef>(&src));
         return handle(reinterpret_cast<PyObject *>(tmp));
     }
 };
@@ -164,8 +164,8 @@ template <> struct type_caster<sycl::event>
     {
         PyObject *source = src.ptr();
         if (PyObject_TypeCheck(source, &PySyclEventType)) {
-            DPCTLSyclEventRef ERef =
-                get_event_ref(reinterpret_cast<PySyclEventObject *>(source));
+            DPCTLSyclEventRef ERef = SyclEvent_GetEventRef(
+                reinterpret_cast<PySyclEventObject *>(source));
             sycl::event *ev = reinterpret_cast<sycl::event *>(ERef);
             value = *ev;
             return true;
@@ -178,7 +178,7 @@ template <> struct type_caster<sycl::event>
 
     static handle cast(sycl::event src, return_value_policy, handle)
     {
-        auto tmp = make_SyclEvent(reinterpret_cast<DPCTLSyclEventRef>(&src));
+        auto tmp = SyclEvent_Make(reinterpret_cast<DPCTLSyclEventRef>(&src));
         return handle(reinterpret_cast<PyObject *>(tmp));
     }
 };

dpctl/apis/include/dpctl_capi.h

@@ -36,6 +36,10 @@
 #include "../_sycl_event_api.h"
 #include "../_sycl_queue.h"
 #include "../_sycl_queue_api.h"
+#include "../memory/_memory.h"
+#include "../memory/_memory_api.h"
+#include "../tensor/_usmarray.h"
+#include "../tensor/_usmarray_api.h"
 // clang-format on
 
 /*
@@ -50,6 +54,7 @@ void import_dpctl(void)
     import_dpctl___sycl_context();
     import_dpctl___sycl_event();
     import_dpctl___sycl_queue();
-
+    import_dpctl__memory___memory();
+    import_dpctl__tensor___usmarray();
     return;
 }

dpctl/memory/_memory.pyx

@@ -751,11 +751,30 @@ def as_usm_memory(obj):
         )
 
 
-cdef api DPCTLSyclUSMRef get_usm_pointer(_Memory obj):
+cdef api DPCTLSyclUSMRef Memory_GetUsmPointer(_Memory obj):
+    "Pointer of USM allocation"
     return obj.memory_ptr
 
-cdef api DPCTLSyclContextRef get_context(_Memory obj):
+cdef api DPCTLSyclContextRef Memory_GetContextRef(_Memory obj):
+    "Context reference to which USM allocation is bound"
     return obj.queue._context.get_context_ref()
 
-cdef api size_t get_nbytes(_Memory obj):
+cdef api DPCTLSyclQueueRef Memory_GetQueueRef(_Memory obj):
+    """Queue associated with this allocation, used
+    for copying, population, etc."""
+    return obj.queue.get_queue_ref()
+
+cdef api size_t Memory_GetNumBytes(_Memory obj):
+    "Size of the allocation in bytes."
     return <size_t>obj.nbytes
+
+cdef api object Memory_Make(
+    DPCTLSyclUSMRef ptr,
+    size_t nbytes,
+    DPCTLSyclQueueRef QRef,
+    object owner
+):
+    "Create _Memory Python object from preallocated memory."
+    return _Memory.create_from_usm_pointer_size_qref(
+        ptr, nbytes, QRef, memory_owner=owner
+    )

dpctl/tensor/_usmarray.pyx

@@ -1136,37 +1136,36 @@ cdef usm_ndarray _zero_like(usm_ndarray ary):
     return r
 
 
-cdef api char* usm_ndarray_get_data(usm_ndarray arr):
-    """
-    """
+cdef api char* UsmNDArray_GetData(usm_ndarray arr):
+    """Get allocation pointer of zero index element of array """
     return arr.get_data()
 
 
-cdef api int usm_ndarray_get_ndim(usm_ndarray arr):
-    """"""
+cdef api int UsmNDArray_GetNDim(usm_ndarray arr):
+    """Get array rank: length of its shape"""
     return arr.get_ndim()
 
 
-cdef api Py_ssize_t* usm_ndarray_get_shape(usm_ndarray arr):
-    """ """
+cdef api Py_ssize_t* UsmNDArray_GetShape(usm_ndarray arr):
+    """Get host pointer to shape vector"""
     return arr.get_shape()
 
 
-cdef api Py_ssize_t* usm_ndarray_get_strides(usm_ndarray arr):
-    """ """
+cdef api Py_ssize_t* UsmNDArray_GetStrides(usm_ndarray arr):
+    """Get host pointer to strides vector"""
     return arr.get_strides()
 
 
-cdef api int usm_ndarray_get_typenum(usm_ndarray arr):
-    """ """
+cdef api int UsmNDArray_GetTypenum(usm_ndarray arr):
+    """Get type number for data type of array elements"""
     return arr.get_typenum()
 
 
-cdef api int usm_ndarray_get_flags(usm_ndarray arr):
-    """ """
+cdef api int UsmNDArray_GetFlags(usm_ndarray arr):
+    """Get flags of array"""
     return arr.get_flags()
 
 
-cdef api c_dpctl.DPCTLSyclQueueRef usm_ndarray_get_queue_ref(usm_ndarray arr):
-    """ """
+cdef api c_dpctl.DPCTLSyclQueueRef UsmNDArray_GetQueueRef(usm_ndarray arr):
+    """Get DPCTLSyclQueueRef for queue associated with the array"""
     return arr.get_queue_ref()

dpctl/tests/test_sycl_context.py

@@ -190,15 +190,15 @@ def test_context_repr():
     assert type(ctx.__repr__()) is str
 
 
-def test_cpython_api_get_context_ref():
+def test_cpython_api_SyclContext_GetContextRef():
     import ctypes
     import sys
 
     ctx = dpctl.SyclContext()
     mod = sys.modules[ctx.__class__.__module__]
-    # get capsule storign get_context_ref function ptr
-    ctx_ref_fn_cap = mod.__pyx_capi__["get_context_ref"]
-    # construct Python callable to invoke "get_context_ref"
+    # get capsule storign SyclContext_GetContextRef function ptr
+    ctx_ref_fn_cap = mod.__pyx_capi__["SyclContext_GetContextRef"]
+    # construct Python callable to invoke "SyclContext_GetContextRef"
     cap_ptr_fn = ctypes.pythonapi.PyCapsule_GetPointer
     cap_ptr_fn.restype = ctypes.c_void_p
     cap_ptr_fn.argtypes = [ctypes.py_object, ctypes.c_char_p]
@@ -213,15 +213,15 @@ def test_cpython_api_get_context_ref():
     assert r1 == r2
 
 
-def test_cpython_api_make_SyclContext():
+def test_cpython_api_SyclContext_Make():
     import ctypes
     import sys
 
     ctx = dpctl.SyclContext()
     mod = sys.modules[ctx.__class__.__module__]
-    # get capsule storign make_SyclContext function ptr
-    make_ctx_fn_cap = mod.__pyx_capi__["make_SyclContext"]
-    # construct Python callable to invoke "make_SyclContext"
+    # get capsule storign SyclContext_Make function ptr
+    make_ctx_fn_cap = mod.__pyx_capi__["SyclContext_Make"]
+    # construct Python callable to invoke "SyclContext_Make"
     cap_ptr_fn = ctypes.pythonapi.PyCapsule_GetPointer
     cap_ptr_fn.restype = ctypes.c_void_p
     cap_ptr_fn.argtypes = [ctypes.py_object, ctypes.c_char_p]

dpctl/tests/test_sycl_device.py

@@ -731,15 +731,15 @@ def test_handle_no_device():
         dpctl.select_device_with_aspects("cpu", excluded_aspects="cpu")
 
 
-def test_cpython_api_get_device_ref():
+def test_cpython_api_SyclDevice_GetDeviceRef():
     import ctypes
     import sys
 
     d = dpctl.SyclDevice()
     mod = sys.modules[d.__class__.__module__]
-    # get capsule storign get_device_ref function ptr
-    d_ref_fn_cap = mod.__pyx_capi__["get_device_ref"]
-    # construct Python callable to invoke "get_device_ref"
+    # get capsule storing SyclDevice_GetDeviceRef function ptr
+    d_ref_fn_cap = mod.__pyx_capi__["SyclDevice_GetDeviceRef"]
+    # construct Python callable to invoke "SyclDevice_GetDeviceRef"
     cap_ptr_fn = ctypes.pythonapi.PyCapsule_GetPointer
     cap_ptr_fn.restype = ctypes.c_void_p
     cap_ptr_fn.argtypes = [ctypes.py_object, ctypes.c_char_p]
@@ -754,15 +754,15 @@ def test_cpython_api_get_device_ref():
     assert r1 == r2
 
 
-def test_cpython_api_make_SyclDevice():
+def test_cpython_api_SyclDevice_Make():
     import ctypes
     import sys
 
     d = dpctl.SyclDevice()
     mod = sys.modules[d.__class__.__module__]
-    # get capsule storign make_SyclContext function ptr
-    make_d_fn_cap = mod.__pyx_capi__["make_SyclDevice"]
-    # construct Python callable to invoke "make_SyclDevice"
+    # get capsule storign SyclContext_Make function ptr
+    make_d_fn_cap = mod.__pyx_capi__["SyclDevice_Make"]
+    # construct Python callable to invoke "SyclDevice_Make"
     cap_ptr_fn = ctypes.pythonapi.PyCapsule_GetPointer
     cap_ptr_fn.restype = ctypes.c_void_p
     cap_ptr_fn.argtypes = [ctypes.py_object, ctypes.c_char_p]