Adds dpctl.SyclQueue.memcpy_async

Also extends `dpctl.SyclQueue.memcpy` to allow arguments to be objects
that expose buffer protocol, allowing `dpctl.SyclQueue.memcpy` and
`dpctl.SyclQueue.memcpy_async` to be used to copy from/to USM-allocation
or host buffer.

Author: oleksandr-pavlyk

dpctl/_backend.pxd

@@ -403,6 +403,13 @@ cdef extern from "syclinterface/dpctl_sycl_queue_interface.h":
         void *Dest,
         const void *Src,
         size_t Count)
+    cdef DPCTLSyclEventRef DPCTLQueue_MemcpyWithEvents(
+        const DPCTLSyclQueueRef Q,
+        void *Dest,
+        const void *Src,
+        size_t Count,
+        const DPCTLSyclEventRef *depEvents,
+        size_t depEventsCount)
     cdef DPCTLSyclEventRef DPCTLQueue_Memset(
         const DPCTLSyclQueueRef Q,
         void *Dest,

dpctl/_sycl_queue.pxd

@@ -96,7 +96,7 @@ cdef public api class SyclQueue (_SyclQueue) [
     cpdef void wait(self)
     cdef DPCTLSyclQueueRef get_queue_ref(self)
     cpdef memcpy(self, dest, src, size_t count)
-    cpdef SyclEvent memcpy_async(self, dest, src, size_t count)
+    cpdef SyclEvent memcpy_async(self, dest, src, size_t count, list dEvents=*)
     cpdef prefetch(self, ptr, size_t count=*)
     cpdef mem_advise(self, ptr, size_t count, int mem)
     cpdef SyclEvent submit_barrier(self, dependent_events=*)

dpctl/_sycl_queue.pyx

@@ -45,6 +45,7 @@ from ._backend cimport (  # noqa: E211
     DPCTLQueue_IsInOrder,
     DPCTLQueue_MemAdvise,
     DPCTLQueue_Memcpy,
+    DPCTLQueue_MemcpyWithEvents,
     DPCTLQueue_Prefetch,
     DPCTLQueue_SubmitBarrierForEvents,
     DPCTLQueue_SubmitNDRange,
@@ -65,6 +66,7 @@ import ctypes
 from .enum_types import backend_type
 
 from cpython cimport pycapsule
+from cpython.buffer cimport PyObject_CheckBuffer
 from cpython.ref cimport Py_DECREF, Py_INCREF, PyObject
 from libc.stdlib cimport free, malloc
 
@@ -173,6 +175,62 @@ cdef void _queue_capsule_deleter(object o) noexcept:
         DPCTLQueue_Delete(QRef)
 
 
+cdef bint _is_buffer(object o):
+    return PyObject_CheckBuffer(o)
+
+
+cdef DPCTLSyclEventRef _memcpy_impl(
+     SyclQueue q,
+     object dst,
+     object src,
+     size_t byte_count,
+     DPCTLSyclEventRef *dep_events,
+     size_t dep_events_count
+):
+    cdef void *c_dst_ptr = NULL
+    cdef void *c_src_ptr = NULL
+    cdef DPCTLSyclEventRef ERef = NULL
+    cdef const unsigned char[::1] src_host_buf = None
+    cdef unsigned char[::1] dst_host_buf = None
+
+    if isinstance(src, _Memory):
+        c_src_ptr = <void*>(<_Memory>src).memory_ptr
+    elif _is_buffer(src):
+        src_host_buf = src
+        c_src_ptr = <void *>&src_host_buf[0]
+    else:
+        raise TypeError(
+             "Parameter `src` should have either type "
+             "`dpctl.memory._Memory` or a type that "
+             "supports Python buffer protocol"
+       )
+
+    if isinstance(dst, _Memory):
+        c_dst_ptr = <void*>(<_Memory>dst).memory_ptr
+    elif _is_buffer(dst):
+        dst_host_buf = dst
+        c_dst_ptr = <void *>&dst_host_buf[0]
+    else:
+        raise TypeError(
+             "Parameter `dst` should have either type "
+             "`dpctl.memory._Memory` or a type that "
+             "supports Python buffer protocol"
+       )
+
+    if dep_events_count == 0 or dep_events is NULL:
+        ERef = DPCTLQueue_Memcpy(q._queue_ref, c_dst_ptr, c_src_ptr, byte_count)
+    else:
+        ERef = DPCTLQueue_MemcpyWithEvents(
+            q._queue_ref,
+            c_dst_ptr,
+            c_src_ptr,
+            byte_count,
+            dep_events,
+            dep_events_count
+        )
+    return ERef
+
+
 cdef class _SyclQueue:
     """ Barebone data owner class used by SyclQueue.
     """
@@ -938,44 +996,44 @@ cdef class SyclQueue(_SyclQueue):
         with nogil: DPCTLQueue_Wait(self._queue_ref)
 
     cpdef memcpy(self, dest, src, size_t count):
-        cdef void *c_dest
-        cdef void *c_src
+        """Copy memory from `src` to `dst`"""
         cdef DPCTLSyclEventRef ERef = NULL
 
-        if isinstance(dest, _Memory):
-            c_dest = <void*>(<_Memory>dest).memory_ptr
-        else:
-            raise TypeError("Parameter `dest` should have type _Memory.")
-
-        if isinstance(src, _Memory):
-            c_src = <void*>(<_Memory>src).memory_ptr
-        else:
-            raise TypeError("Parameter `src` should have type _Memory.")
-
-        ERef = DPCTLQueue_Memcpy(self._queue_ref, c_dest, c_src, count)
+        ERef = _memcpy_impl(<SyclQueue>self, dest, src, count, NULL, 0)
         if (ERef is NULL):
             raise RuntimeError(
                 "SyclQueue.memcpy operation encountered an error"
             )
         with nogil: DPCTLEvent_Wait(ERef)
         DPCTLEvent_Delete(ERef)
 
-    cpdef SyclEvent memcpy_async(self, dest, src, size_t count):
-        cdef void *c_dest
-        cdef void *c_src
+    cpdef SyclEvent memcpy_async(self, dest, src, size_t count, list dEvents=None):
+        """Copy memory from `src` to `dst`"""
         cdef DPCTLSyclEventRef ERef = NULL
+        cdef DPCTLSyclEventRef *depEvents = NULL
+        cdef size_t nDE = 0
 
-        if isinstance(dest, _Memory):
-            c_dest = <void*>(<_Memory>dest).memory_ptr
-        else:
-            raise TypeError("Parameter `dest` should have type _Memory.")
-
-        if isinstance(src, _Memory):
-            c_src = <void*>(<_Memory>src).memory_ptr
+        if dEvents is None:
+            ERef = _memcpy_impl(<SyclQueue>self, dest, src, count, NULL, 0)
         else:
-            raise TypeError("Parameter `src` should have type _Memory.")
+            nDE = len(dEvents)
+            depEvents = (
+                <DPCTLSyclEventRef*>malloc(nDE*sizeof(DPCTLSyclEventRef))
+            )
+            if depEvents is NULL:
+                raise MemoryError()
+            else:
+                for idx, de in enumerate(dEvents):
+                    if isinstance(de, SyclEvent):
+                        depEvents[idx] = (<SyclEvent>de).get_event_ref()
+                    else:
+                        free(depEvents)
+                        raise TypeError(
+                            "A sequence of dpctl.SyclEvent is expected"
+                        )
+            ERef = _memcpy_impl(self, dest, src, count, depEvents, nDE)
+            free(depEvents)
 
-        ERef = DPCTLQueue_Memcpy(self._queue_ref, c_dest, c_src, count)
         if (ERef is NULL):
             raise RuntimeError(
                 "SyclQueue.memcpy operation encountered an error"

dpctl/tests/test_sycl_queue_memcpy.py

@@ -44,7 +44,77 @@ def test_memcpy_copy_usm_to_usm():
 
     q.memcpy(mobj2, mobj1, 3)
 
-    assert mv2[:3], b"123"
+    assert mv2[:3] == b"123"
+
+
+def test_memcpy_copy_host_to_usm():
+    try:
+        q = dpctl.SyclQueue()
+    except dpctl.SyclQueueCreationError:
+        pytest.skip("Default constructor for SyclQueue failed")
+    usm_obj = _create_memory(q)
+
+    canary = bytearray(b"123456789")
+    host_obj = memoryview(canary)
+
+    q.memcpy(usm_obj, host_obj, len(canary))
+
+    mv2 = memoryview(usm_obj)
+
+    assert mv2[: len(canary)] == canary
+
+
+def test_memcpy_copy_usm_to_host():
+    try:
+        q = dpctl.SyclQueue()
+    except dpctl.SyclQueueCreationError:
+        pytest.skip("Default constructor for SyclQueue failed")
+    usm_obj = _create_memory(q)
+    mv2 = memoryview(usm_obj)
+
+    n = 9
+    for id in range(n):
+        mv2[id] = ord("a") + id
+
+    host_obj = bytearray(b" " * n)
+
+    q.memcpy(host_obj, usm_obj, n)
+
+    assert host_obj == b"abcdefghi"
+
+
+def test_memcpy_copy_host_to_host():
+    try:
+        q = dpctl.SyclQueue()
+    except dpctl.SyclQueueCreationError:
+        pytest.skip("Default constructor for SyclQueue failed")
+
+    src_buf = b"abcdefghijklmnopqrstuvwxyz"
+    dst_buf = bytearray(len(src_buf))
+
+    q.memcpy(dst_buf, src_buf, len(src_buf))
+
+    assert dst_buf == src_buf
+
+
+def test_memcpy_async():
+    try:
+        q = dpctl.SyclQueue()
+    except dpctl.SyclQueueCreationError:
+        pytest.skip("Default constructor for SyclQueue failed")
+
+    src_buf = b"abcdefghijklmnopqrstuvwxyz"
+    n = len(src_buf)
+    dst_buf = bytearray(n)
+    dst_buf2 = bytearray(n)
+
+    e = q.memcpy_async(dst_buf, src_buf, n)
+    e2 = q.memcpy_async(dst_buf2, src_buf, n)
+
+    e2.wait()
+    e.wait()
+    assert dst_buf == src_buf
+    assert dst_buf2 == src_buf
 
 
 def test_memcpy_type_error():
@@ -56,8 +126,8 @@ def test_memcpy_type_error():
 
     with pytest.raises(TypeError) as cm:
         q.memcpy(None, mobj, 3)
-    assert "`dest`" in str(cm.value)
+    assert "_Memory" in str(cm.value)
 
     with pytest.raises(TypeError) as cm:
         q.memcpy(mobj, None, 3)
-    assert "`src`" in str(cm.value)
+    assert "_Memory" in str(cm.value)