Standardizes the names of DPPL functions (#44)

* Move _memory.pyx

* Import setuptools before Cython. Otherwise, both might disagree about the class to use.

* Add dppl._memory Cython module.

* Run dppl/tests/dppl_tests too when run all unit tests.

* Add tests for memory manager.

* Split tests for memory. One test one context (no, CPU, GPU).

* [opt] Rename getpyexts() to extensions().

* Adds C and Cython API for portions of Sycl queue, device, context interfaces.

     - Separates out the queue manager from the sycl queue interface wrapper.
     - Added API to get context, device froma  Sycl queue.
     - Added C-API wrappers for sycl device, queue, context interfaces exposing
       some of the API functionalities. More can be added as needed.
     - The dppl extension now defines extension types for sycl quque, device, context to
       mimic the C API.
     - Sycl queues are now returned to callers as a SyclQueue extension type rather than
       a Py_capsule.

* Add C-API stub library for sycl memory.

* Add missing DPPL_API.

* Move platform specific functions into a separate file.

* Create a single utility function to delete C strings.

* Update backends/source/dppl_utils.cpp

New line at EOF.

* Add _sycl_core.pxd file.

* Remove using of PyCapsule in _memory.pyx.

* Small style fixes in _memory.pyx.

* Moved functions from _memory.pyx to C-API interface library.

* Move Cython definitions for backend to single pxd file.

* Remove SyclQueue from _memory.pyx

* Use SyclQueue from

* Remove cl::sycl::queue from _memory.pyx

* Removed commented code from _memory.pyx

* Eliminate temporary context object.

* Fix style.

* Add MemoryUSM* classes.

* Add __getbuffer__ to Shared and Host MemoryUSM classes.

* Rename C-API types for USM.

* Add DPPLUSM_GetPointerType and remove types from CL/sycl.hpp from _memory.pyx

* Clean unused code from _memory_.pyx

* Small fixes.

* Remove unused code.

* Fix style.

* Fix style

* Use wrap().

* Store context instead of queue in Memory class.

* Pass queue as parameter to constructor. If queue is None then get dppl current queue.

* Add comment about casting memory_ptr to char*.

* Remove pointer property from Memory.

* Rename file with usm tests.

* Standardize the names of DPPL functions on DPPLXXX_FuncName.

* Fix files.

* Rename the CString deleter to follow convention in rest of the library.

Co-authored-by: Sergey Pokhodenko <[email protected]>
Co-authored-by: Sergey Pokhodenko <[email protected]>

Author: diptorupd

backends/include/dppl_sycl_context_interface.h

@@ -37,18 +37,18 @@ DPPL_C_EXTERN_C_BEGIN
 /*!
  * @brief Returns true if this SYCL context is a host context.
  *
- * @param    CtxtRef        A opaque pointer to a sycl::context.
+ * @param    CtxRef        A opaque pointer to a sycl::context.
  * @return   True if the SYCL context is a host context, else False.
  */
 DPPL_API
-bool DPPLIsHostContext (__dppl_keep const DPPLSyclContextRef CtxtRef);
+bool DPPLContext_IsHost (__dppl_keep const DPPLSyclContextRef CtxRef);
 
 /*!
  * @brief Delete the pointer after casting it to sycl::context
  *
- * @param    CtxtRef        The DPPLSyclContextRef pointer to be deleted.
+ * @param    CtxRef        The DPPLSyclContextRef pointer to be deleted.
  */
 DPPL_API
-void DPPLDeleteSyclContext (__dppl_take DPPLSyclContextRef CtxtRef);
+void DPPLContext_Delete (__dppl_take DPPLSyclContextRef CtxRef);
 
 DPPL_C_EXTERN_C_END

backends/include/dppl_sycl_device_interface.h

@@ -57,15 +57,15 @@ typedef enum
  * @param    DRef           A DPPLSyclDeviceRef pointer.
  */
 DPPL_API
-void DPPLDumpDeviceInfo (__dppl_keep const DPPLSyclDeviceRef DRef);
+void DPPLDevice_DumpInfo (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Deletes a DPPLSyclDeviceRef pointer after casting to to sycl::device.
  *
  * @param    DRef           The DPPLSyclDeviceRef pointer to be freed.
  */
 DPPL_API
-void DPPLDeleteSyclDevice (__dppl_take DPPLSyclDeviceRef DRef);
+void DPPLDevice_Delete (__dppl_take DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is an OpenCL device and the device
@@ -75,7 +75,7 @@ void DPPLDeleteSyclDevice (__dppl_take DPPLSyclDeviceRef DRef);
  * @return   True if the device type is an accelerator, else False.
  */
 DPPL_API
-bool DPPLDeviceIsAccelerator (__dppl_keep const DPPLSyclDeviceRef DRef);
+bool DPPLDevice_IsAccelerator (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is an OpenCL device and the device
@@ -85,7 +85,7 @@ bool DPPLDeviceIsAccelerator (__dppl_keep const DPPLSyclDeviceRef DRef);
  * @return   True if the device type is a cpu, else False.
  */
 DPPL_API
-bool DPPLDeviceIsCPU (__dppl_keep const DPPLSyclDeviceRef DRef);
+bool DPPLDevice_IsCPU (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is an OpenCL device and the device
@@ -95,7 +95,7 @@ bool DPPLDeviceIsCPU (__dppl_keep const DPPLSyclDeviceRef DRef);
  * @return    True if the device type is a gpu, else False.
  */
 DPPL_API
-bool DPPLDeviceIsGPU (__dppl_keep const DPPLSyclDeviceRef DRef);
+bool DPPLDevice_IsGPU (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns true if this SYCL device is a host device.
@@ -104,7 +104,7 @@ bool DPPLDeviceIsGPU (__dppl_keep const DPPLSyclDeviceRef DRef);
  * @return   True if the device is a host device, else False.
  */
 DPPL_API
-bool DPPLDeviceIsHost (__dppl_keep const DPPLSyclDeviceRef DRef);
+bool DPPLDevice_IsHost (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns the OpenCL software driver version as a C string.
@@ -115,7 +115,7 @@ bool DPPLDeviceIsHost (__dppl_keep const DPPLSyclDeviceRef DRef);
  */
 DPPL_API
 __dppl_give const char*
-DPPLGetDeviceDriverInfo (__dppl_keep const DPPLSyclDeviceRef DRef);
+DPPLDevice_GetDriverInfo (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns a C string for the device name.
@@ -125,7 +125,7 @@ DPPLGetDeviceDriverInfo (__dppl_keep const DPPLSyclDeviceRef DRef);
  */
 DPPL_API
 __dppl_give const char*
-DPPLGetDeviceName (__dppl_keep const DPPLSyclDeviceRef DRef);
+DPPLDevice_GetName (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns a C string corresponding to the vendor name.
@@ -135,7 +135,7 @@ DPPLGetDeviceName (__dppl_keep const DPPLSyclDeviceRef DRef);
  */
 DPPL_API
 __dppl_give const char*
-DPPLGetDeviceVendorName (__dppl_keep const DPPLSyclDeviceRef DRef);
+DPPLDevice_GetVendorName (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 /*!
  * @brief Returns True if the device and the host share a unified memory
@@ -146,6 +146,6 @@ DPPLGetDeviceVendorName (__dppl_keep const DPPLSyclDeviceRef DRef);
  * with the host.
  */
 DPPL_API
-bool DPPLGetDeviceHostUnifiedMemory (__dppl_keep const DPPLSyclDeviceRef DRef);
+bool DPPLDevice_IsHostUnifiedMemory (__dppl_keep const DPPLSyclDeviceRef DRef);
 
 DPPL_C_EXTERN_C_END

backends/include/dppl_sycl_queue_interface.h

@@ -43,7 +43,7 @@ DPPL_C_EXTERN_C_BEGIN
  */
 DPPL_API
 __dppl_give DPPLSyclContextRef
-DPPLGetContextFromQueue (__dppl_keep const DPPLSyclQueueRef QRef);
+DPPLQueue_GetContext (__dppl_keep const DPPLSyclQueueRef QRef);
 
 /*!
  * @brief returns the Sycl device for the queue.
@@ -53,14 +53,14 @@ DPPLGetContextFromQueue (__dppl_keep const DPPLSyclQueueRef QRef);
  */
 DPPL_API
 __dppl_give DPPLSyclDeviceRef
-DPPLGetDeviceFromQueue (__dppl_keep const DPPLSyclQueueRef QRef);
+DPPLQueue_GetDevice (__dppl_keep const DPPLSyclQueueRef QRef);
 
 /*!
  * @brief Delete the pointer after casting it to sycl::queue.
  *
  * @param    QRef           A DPPLSyclQueueRef pointer that gets deleted.
  */
 DPPL_API
-void DPPLDeleteSyclQueue (__dppl_take DPPLSyclQueueRef QRef);
+void DPPLQueue_Delete (__dppl_take DPPLSyclQueueRef QRef);
 
 DPPL_C_EXTERN_C_END

backends/include/dppl_sycl_queue_manager.h

@@ -50,7 +50,7 @@ DPPL_C_EXTERN_C_BEGIN
  * wrapped inside an opaque DPPLSyclQueueRef pointer.
  */
 DPPL_API
-__dppl_give DPPLSyclQueueRef DPPLGetCurrentQueue ();
+__dppl_give DPPLSyclQueueRef DPPLQueueMgr_GetCurrentQueue ();
 
 /*!
  * @brief Get a sycl::queue object of the specified type and device id.
@@ -63,8 +63,8 @@ __dppl_give DPPLSyclQueueRef DPPLGetCurrentQueue ();
  * raised if no such device exists.
  */
 DPPL_API
-__dppl_give DPPLSyclQueueRef DPPLGetQueue (DPPLSyclDeviceType DeviceTy,
-                                           size_t DNum);
+__dppl_give DPPLSyclQueueRef DPPLQueueMgr_GetQueue (DPPLSyclDeviceType DeviceTy,
+                                                    size_t DNum);
 
 /*!
  * @brief Get the number of activated queues not including the global or
@@ -73,23 +73,23 @@ __dppl_give DPPLSyclQueueRef DPPLGetQueue (DPPLSyclDeviceType DeviceTy,
  * @return The number of activated queues.
  */
 DPPL_API
-size_t DPPLGetNumActivatedQueues ();
+size_t DPPLQueueMgr_GetNumActivatedQueues ();
 
 /*!
  * @brief Get the number of GPU queues available on the system.
  *
  * @return The number of available GPU queues.
  */
 DPPL_API
-size_t DPPLGetNumGPUQueues ();
+size_t DPPLQueueMgr_GetNumGPUQueues ();
 
 /*!
  * @brief Get the number of CPU queues available on the system.
  *
  * @return The number of available CPU queues.
  */
 DPPL_API
-size_t DPPLGetNumCPUQueues ();
+size_t DPPLQueueMgr_GetNumCPUQueues ();
 
 /*!
 * @brief Set the default DPPL queue to the sycl::queue for the given device.
@@ -100,8 +100,8 @@ size_t DPPLGetNumCPUQueues ();
 * @param    DNum           Device id for the device (defaults to 0)
 */
 DPPL_API
-void DPPLSetAsDefaultQueue (DPPLSyclDeviceType DeviceTy,
-                            size_t DNum);
+void DPPLQueueMgr_SetAsDefaultQueue (DPPLSyclDeviceType DeviceTy,
+                                     size_t DNum);
 
 /*!
  * @brief Pushes a new sycl::queue object to the top of DPPL's thread-local
@@ -110,11 +110,11 @@ void DPPLSetAsDefaultQueue (DPPLSyclDeviceType DeviceTy,
  * DPPL maintains a thread-local stack of sycl::queue objects to facilitate
  * nested parallelism. The sycl::queue at the top of the stack is termed as the
  * currently activated queue, and is always the one returned by
- * DPPLGetCurrentQueue(). DPPLPushSyclQueueToStack creates a new sycl::queue
- * corresponding to the specified device and pushes it to the top of the stack.
- * A copy of the sycl::queue is returned to the caller wrapped inside the
- * opaque DPPLSyclQueueRef pointer. A runtime_error exception is thrown when
- * a new sycl::queue could not be created for the specified device.
+ * DPPLQueueMgr_GetCurrentQueue(). DPPLPushSyclQueueToStack creates a new
+ * sycl::queue corresponding to the specified device and pushes it to the top
+ * of the stack. A copy of the sycl::queue is returned to the caller wrapped
+ * inside the opaque DPPLSyclQueueRef pointer. A runtime_error exception is
+ * thrown when a new sycl::queue could not be created for the specified device.
  *
  * @param    DeviceTy       The type of Sycl device (sycl_device_type)
  * @param    DNum           Device id for the device (defaults to 0)
@@ -123,21 +123,21 @@ void DPPLSetAsDefaultQueue (DPPLSyclDeviceType DeviceTy,
  * stack of sycl::queue objects.
  */
 DPPL_API
-__dppl_give DPPLSyclQueueRef DPPLPushSyclQueue (DPPLSyclDeviceType DeviceTy,
-                                                size_t DNum);
+__dppl_give DPPLSyclQueueRef
+DPPLQueueMgr_PushQueue (DPPLSyclDeviceType DeviceTy, size_t DNum);
 
 /*!
  * @brief Pops the top of stack element from DPPL's stack of activated
  * sycl::queue objects.
  *
  * DPPLPopSyclQueue only removes the reference from the DPPL stack of
  * sycl::queue objects. Any instance of the popped queue that were previously
- * acquired by calling DPPLPushSyclQueue() or DPPLGetCurrentQueue() needs to be
- * freed separately. In addition, a runtime_error is thrown when the stack
- * contains only one sycl::queue, i.e., the default queue.
+ * acquired by calling DPPLPushSyclQueue() or DPPLQueueMgr_GetCurrentQueue()
+ * needs to be freed separately. In addition, a runtime_error is thrown when
+ * the stack contains only one sycl::queue, i.e., the default queue.
  *
  */
 DPPL_API
-void DPPLPopSyclQueue ();
+void DPPLQueueMgr_PopQueue ();
 
 DPPL_C_EXTERN_C_END

backends/include/dppl_utils.h

@@ -36,6 +36,6 @@ DPPL_C_EXTERN_C_BEGIN
  * @param    str            C string to be deleted
  */
 DPPL_API
-void DPPLDeleteCString (__dppl_take const char* str);
+void DPPLCString_Delete (__dppl_take const char* str);
 
 DPPL_C_EXTERN_C_END

backends/source/dppl_sycl_context_interface.cpp

@@ -42,17 +42,17 @@ namespace
  * @param    CtxtRef        My Param doc
  * @return   {return}       My Param doc
  */
-bool DPPLIsHostContext (__dppl_keep const DPPLSyclContextRef CtxtRef)
+bool DPPLContext_IsHost (__dppl_keep const DPPLSyclContextRef CtxRef)
 {
-    return unwrap(CtxtRef)->is_host();
+    return unwrap(CtxRef)->is_host();
 }
 
 /*!
  * @brief
  *
  * @param    CtxtRef        My Param doc
  */
-void DPPLDeleteSyclContext (__dppl_take DPPLSyclContextRef CtxtRef)
+void DPPLContext_Delete (__dppl_take DPPLSyclContextRef CtxRef)
 {
-    delete unwrap(CtxtRef);
+    delete unwrap(CtxRef);
 }

backends/source/dppl_sycl_device_interface.cpp

@@ -66,41 +66,41 @@ void dump_device_info (const device & Device)
  * vendor, and device profile are printed out. More attributed may be added
  * later.
  */
-void DPPLDumpDeviceInfo (__dppl_keep const DPPLSyclDeviceRef DRef)
+void DPPLDevice_DumpInfo (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     auto Device = unwrap(DRef);
     dump_device_info(*Device);
 }
 
 
-void DPPLDeleteSyclDevice (__dppl_take DPPLSyclDeviceRef DRef)
+void DPPLDevice_Delete (__dppl_take DPPLSyclDeviceRef DRef)
 {
     delete unwrap(DRef);
 }
 
-bool DPPLDeviceIsAccelerator (__dppl_keep const DPPLSyclDeviceRef DRef)
+bool DPPLDevice_IsAccelerator (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     return unwrap(DRef)->is_accelerator();
 }
 
-bool DPPLDeviceIsCPU (__dppl_keep const DPPLSyclDeviceRef DRef)
+bool DPPLDevice_IsCPU (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     return unwrap(DRef)->is_cpu();
 }
 
-bool DPPLDeviceIsGPU (__dppl_keep const DPPLSyclDeviceRef DRef)
+bool DPPLDevice_IsGPU (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     return unwrap(DRef)->is_gpu();
 }
 
 
-bool DPPLDeviceIsHost (__dppl_keep const DPPLSyclDeviceRef DRef)
+bool DPPLDevice_IsHost (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     return unwrap(DRef)->is_host();
 }
 
 __dppl_give const char*
-DPPLGetDeviceName (__dppl_keep const DPPLSyclDeviceRef DRef)
+DPPLDevice_GetName (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     auto name = unwrap(DRef)->get_info<info::device::name>();
     auto cstr_name = new char [name.length()+1];
@@ -109,7 +109,7 @@ DPPLGetDeviceName (__dppl_keep const DPPLSyclDeviceRef DRef)
 }
 
 __dppl_give const char*
-DPPLGetDeviceVendorName (__dppl_keep const DPPLSyclDeviceRef DRef)
+DPPLDevice_GetVendorName (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     auto vendor = unwrap(DRef)->get_info<info::device::name>();
     auto cstr_vendor = new char [vendor.length()+1];
@@ -118,15 +118,15 @@ DPPLGetDeviceVendorName (__dppl_keep const DPPLSyclDeviceRef DRef)
 }
 
 __dppl_give const char*
-DPPLGetDeviceDriverInfo (__dppl_keep const DPPLSyclDeviceRef DRef)
+DPPLDevice_GetDriverInfo (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     auto driver = unwrap(DRef)->get_info<info::device::driver_version>();
     auto cstr_driver = new char [driver.length()+1];
     std::strcpy (cstr_driver, driver.c_str());
     return cstr_driver;
 }
 
-bool DPPLGetDeviceHostUnifiedMemory (__dppl_keep const DPPLSyclDeviceRef DRef)
+bool DPPLDevice_IsHostUnifiedMemory (__dppl_keep const DPPLSyclDeviceRef DRef)
 {
     return unwrap(DRef)->get_info<info::device::host_unified_memory>();
 }

backends/source/dppl_sycl_queue_interface.cpp

@@ -39,15 +39,15 @@ namespace
 } /* end of anonymous namespace */
 
 __dppl_give DPPLSyclDeviceRef
-DPPLGetDeviceFromQueue (__dppl_keep const DPPLSyclQueueRef QRef)
+DPPLQueue_GetDevice (__dppl_keep const DPPLSyclQueueRef QRef)
 {
     auto Q = unwrap(QRef);
     auto Device = new device(Q->get_device());
     return reinterpret_cast<DPPLSyclDeviceRef>(Device);
 }
 
 __dppl_give DPPLSyclContextRef
-DPPLGetContextFromQueue (__dppl_keep const DPPLSyclQueueRef QRef)
+DPPLQueue_GetContext (__dppl_keep const DPPLSyclQueueRef QRef)
 {
     auto Q = unwrap(QRef);
     auto Context = new context(Q->get_context());
@@ -57,7 +57,7 @@ DPPLGetContextFromQueue (__dppl_keep const DPPLSyclQueueRef QRef)
 /*!
  * Delete the passed in pointer after verifying it points to a sycl::queue.
  */
-void DPPLDeleteSyclQueue (__dppl_take DPPLSyclQueueRef QRef)
+void DPPLQueue_Delete (__dppl_take DPPLSyclQueueRef QRef)
 {
     delete unwrap(QRef);
 }