task: syclqueue.copy() method

Author: jharlow-intel

dpctl/_sycl_queue.pxd

@@ -103,6 +103,8 @@ cdef public api class SyclQueue (_SyclQueue) [
     cdef DPCTLSyclQueueRef get_queue_ref(self)
     cpdef memcpy(self, dest, src, size_t count)
     cpdef SyclEvent memcpy_async(self, dest, src, size_t count, list dEvents=*)
+    cpdef copy(self, dest, src, size_t count)
+    cpdef SyclEvent copy_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

@@ -1426,6 +1426,76 @@ cdef class SyclQueue(_SyclQueue):
 
         return SyclEvent._create(ERef)
 
+    cpdef copy(self, dest, src, size_t count):
+        """Copy ``count`` bytes from ``src`` to ``dest`` and wait.
+
+        This is a synchronizing variant corresponding to
+        :meth:`dpctl.SyclQueue.copy_async`.
+        """
+        cdef DPCTLSyclEventRef ERef = NULL
+
+        ERef = _memcpy_impl(<SyclQueue>self, dest, src, count, NULL, 0)
+        if (ERef is NULL):
+            raise RuntimeError(
+                "SyclQueue.copy operation encountered an error"
+            )
+        with nogil:
+            DPCTLEvent_Wait(ERef)
+        DPCTLEvent_Delete(ERef)
+
+    cpdef SyclEvent copy_async(
+        self, dest, src, size_t count, list dEvents=None
+    ):
+        """Copy ``count`` bytes from ``src`` to ``dest`` asynchronously.
+
+        Args:
+            dest:
+                Destination USM object or Python object supporting
+                writable buffer protocol.
+            src:
+                Source USM object or Python object supporting buffer
+                protocol.
+            count (int):
+                Number of bytes to copy.
+            dEvents (List[dpctl.SyclEvent], optional):
+                Events that this copy depends on.
+
+        Returns:
+            dpctl.SyclEvent:
+                Event associated with the copy operation.
+        """
+        cdef DPCTLSyclEventRef ERef = NULL
+        cdef DPCTLSyclEventRef *depEvents = NULL
+        cdef size_t nDE = 0
+
+        if dEvents is None:
+            ERef = _memcpy_impl(<SyclQueue>self, dest, src, count, NULL, 0)
+        else:
+            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)
+
+        if (ERef is NULL):
+            raise RuntimeError(
+                "SyclQueue.copy operation encountered an error"
+            )
+
+        return SyclEvent._create(ERef)
+
     cpdef prefetch(self, mem, size_t count=0):
         cdef void *ptr
         cdef DPCTLSyclEventRef ERef = NULL

dpctl/tests/test_sycl_queue_copy.py

@@ -0,0 +1,78 @@
+#                      Data Parallel Control (dpctl)
+#
+# Copyright 2020-2025 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines unit test cases for the SyclQueue.copy."""
+
+import pytest
+
+import dpctl
+import dpctl.memory
+
+
+def _create_memory(q):
+    nbytes = 1024
+    mobj = dpctl.memory.MemoryUSMShared(nbytes, queue=q)
+    return mobj
+
+
+def test_copy_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.copy(dst_buf, src_buf, len(src_buf))
+
+    assert dst_buf == src_buf
+
+
+def test_copy_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.copy_async(dst_buf, src_buf, n)
+    e2 = q.copy_async(dst_buf2, src_buf, n, [e])
+
+    e.wait()
+    e2.wait()
+    assert dst_buf == src_buf
+    assert dst_buf2 == src_buf
+
+
+def test_copy_type_error():
+    try:
+        q = dpctl.SyclQueue()
+    except dpctl.SyclQueueCreationError:
+        pytest.skip("Default constructor for SyclQueue failed")
+    mobj = _create_memory(q)
+
+    with pytest.raises(TypeError) as cm:
+        q.copy(None, mobj, 3)
+    assert "_Memory" in str(cm.value)
+
+    with pytest.raises(TypeError) as cm:
+        q.copy(mobj, None, 3)
+    assert "_Memory" in str(cm.value)