Merge pull request #2322 from IntelPython/use_return_tuple

Return tuple instead of list from device and platform collection APIs

Author: ndgrigorian

dpctl/_sycl_context.pyx

@@ -153,7 +153,7 @@ cdef class SyclContext(_SyclContext):
             sub_devices = cpu_d.create_sub_devices(partition=2)
             # Create a context common to all the sub-devices.
             ctx = dpctl.SyclContext(sub_devices)
-            assert(len(ctx.get_devices) == len(sub_devices))
+            assert(len(ctx.get_devices()) == len(sub_devices))
 
     - Invoking the constructor with a named ``PyCapsule`` with name
       **"SyclContextRef"** that carries a pointer to a ``sycl::context``
@@ -388,12 +388,12 @@ cdef class SyclContext(_SyclContext):
 
     def get_devices(self):
         """
-        Returns the list of :class:`dpctl.SyclDevice` objects associated with
+        Returns a tuple of :class:`dpctl.SyclDevice` objects associated with
         :class:`dpctl.SyclContext` instance.
 
         Returns:
-            list:
-                A :obj:`list` of :class:`dpctl.SyclDevice` objects
+            Tuple[:class:`dpctl.SyclDevice`]:
+                A tuple of :class:`dpctl.SyclDevice` objects
                 that belong to this context.
 
         Raises:
@@ -415,7 +415,7 @@ cdef class SyclContext(_SyclContext):
             DRef = DPCTLDeviceVector_GetAt(DVRef, i)
             devices.append(SyclDevice._create(DRef))
         DPCTLDeviceVector_Delete(DVRef)
-        return devices
+        return tuple(devices)
 
     @property
     def device_count(self):

dpctl/_sycl_device.pxd

@@ -51,9 +51,9 @@ cdef public api class SyclDevice(_SyclDevice) [
     cdef int _init_from__SyclDevice(self, _SyclDevice other)
     cdef int _init_from_selector(self, DPCTLSyclDeviceSelectorRef DSRef)
     cdef DPCTLSyclDeviceRef get_device_ref(self)
-    cdef list create_sub_devices_equally(self, size_t count)
-    cdef list create_sub_devices_by_counts(self, object counts)
-    cdef list create_sub_devices_by_affinity(
+    cdef tuple create_sub_devices_equally(self, size_t count)
+    cdef tuple create_sub_devices_by_counts(self, object counts)
+    cdef tuple create_sub_devices_by_affinity(
         self, _partition_affinity_domain_type domain
     )
     cdef cpp_bool equals(self, SyclDevice q)

dpctl/_sycl_device.pyx

@@ -157,7 +157,7 @@ cdef class _SyclDevice:
         DPCTLSize_t_Array_Delete(self._max_work_item_sizes)
 
 
-cdef list _get_devices(DPCTLDeviceVectorRef DVRef):
+cdef tuple _get_devices(DPCTLDeviceVectorRef DVRef):
     """
     Deletes DVRef. Pass a copy in case an original reference is needed.
     """
@@ -171,7 +171,7 @@ cdef list _get_devices(DPCTLDeviceVectorRef DVRef):
             devices.append(D)
         DPCTLDeviceVector_Delete(DVRef)
 
-    return devices
+    return tuple(devices)
 
 
 cdef str _backend_type_to_filter_string_part(_backend_type BTy):
@@ -1188,7 +1188,7 @@ cdef class SyclDevice(_SyclDevice):
 
     @property
     def sub_group_sizes(self):
-        """ Returns list of supported sub-group sizes for this device.
+        """ Returns tuple of supported sub-group sizes for this device.
 
         :Example:
 
@@ -1197,11 +1197,11 @@ cdef class SyclDevice(_SyclDevice):
                 >>> import dpctl
                 >>> dev = dpctl.select_cpu_device()
                 >>> dev.sub_group_sizes
-                [4, 8, 16, 32, 64]
+                (4, 8, 16, 32, 64)
 
         Returns:
-            List[int]:
-                List of supported sub-group sizes.
+            Tuple[int]:
+                Tuple of supported sub-group sizes.
         """
         cdef size_t *sg_sizes = NULL
         cdef size_t sg_sizes_len = 0
@@ -1214,9 +1214,9 @@ cdef class SyclDevice(_SyclDevice):
             for i in range(sg_sizes_len):
                 res.append(sg_sizes[i])
             DPCTLSize_t_Array_Delete(sg_sizes)
-            return res
+            return tuple(res)
         else:
-            return []
+            return ()
 
     @property
     def sycl_platform(self):
@@ -1590,11 +1590,11 @@ cdef class SyclDevice(_SyclDevice):
         """
         return DPCTLDevice_Hash(self._device_ref)
 
-    cdef list create_sub_devices_equally(self, size_t count):
-        """ Returns a list of sub-devices partitioned from this SYCL device
+    cdef tuple create_sub_devices_equally(self, size_t count):
+        """ Returns a tuple of sub-devices partitioned from this SYCL device
         based on the ``count`` parameter.
 
-        The returned list contains as many sub-devices as can be created
+        The returned tuple contains as many sub-devices as can be created
         such that each sub-device contains count compute units. If the
         device’s total number of compute units is not evenly divided by
         count, then the remaining compute units are not included in any of
@@ -1605,7 +1605,7 @@ cdef class SyclDevice(_SyclDevice):
                 Number of sub-devices to partition into.
 
         Returns:
-            List[:class:`dpctl.SyclDevice`]:
+            Tuple[:class:`dpctl.SyclDevice`]:
                 Created sub-devices.
 
         Raises:
@@ -1623,15 +1623,15 @@ cdef class SyclDevice(_SyclDevice):
             )
         return _get_devices(DVRef)
 
-    cdef list create_sub_devices_by_counts(self, object counts):
-        """ Returns a list of sub-devices partitioned from this SYCL device
+    cdef tuple create_sub_devices_by_counts(self, object counts):
+        """ Returns a tuple of sub-devices partitioned from this SYCL device
         based on the ``counts`` parameter.
 
         For each non-zero value ``M`` in the counts vector, a sub-device
         with ``M`` compute units is created.
 
         Returns:
-            List[:class:`dpctl.SyclDevice`]:
+            Tuple[:class:`dpctl.SyclDevice`]:
                 Created sub-devices.
 
         Raises:
@@ -1670,14 +1670,14 @@ cdef class SyclDevice(_SyclDevice):
             )
         return _get_devices(DVRef)
 
-    cdef list create_sub_devices_by_affinity(
+    cdef tuple create_sub_devices_by_affinity(
         self, _partition_affinity_domain_type domain
     ):
-        """ Returns a list of sub-devices partitioned from this SYCL device by
+        """ Returns a tuple of sub-devices partitioned from this SYCL device by
         affinity domain based on the ``domain`` parameter.
 
         Returns:
-            List[:class:`dpctl.SyclDevice`]:
+            Tuple[:class:`dpctl.SyclDevice`]:
                 Created sub-devices.
 
         Raises:
@@ -1692,8 +1692,8 @@ cdef class SyclDevice(_SyclDevice):
 
     def create_sub_devices(self, **kwargs):
         """create_sub_devices(partition=partition_spec)
-        Creates a list of sub-devices by partitioning a root device based on the
-        provided partition specifier.
+        Creates a tuple of sub-devices by partitioning a root device based on
+        the provided partition specifier.
 
         A partition specifier must be provided using a ``partition``
         keyword argument. Possible values for the specifier are: an integer, a
@@ -1725,7 +1725,7 @@ cdef class SyclDevice(_SyclDevice):
                 Specification to partition the device as follows:
 
                 - Specifying an int (``count``)
-                    The returned list contains as
+                    The returned tuple contains as
                     many sub-devices as can be created such that each
                     sub-device contains ``count`` compute units. If the
                     device’s total number of compute units is not evenly
@@ -1742,7 +1742,7 @@ cdef class SyclDevice(_SyclDevice):
                     sub-device with ``M`` compute units is created.
 
         Returns:
-            List[:class:`dpctl.SyclDevice`]:
+            Tuple[:class:`dpctl.SyclDevice`]:
                 Created sub-devices.
 
         Raises:
@@ -1831,14 +1831,14 @@ cdef class SyclDevice(_SyclDevice):
         return SyclDevice._create(CDRef)
 
     def component_devices(self):
-        """ Returns a list of component devices contained in this SYCL device.
+        """ Returns a tuple of component devices contained in this SYCL device.
 
-        The returned list will be empty if this SYCL device is not a composite
+        The returned tuple will be empty if this SYCL device is not a composite
         device, i.e., if `is_composite` is ``False``.
 
         Returns:
-            List[:class:`dpctl.SyclDevice`]:
-                List of component devices.
+            Tuple[:class:`dpctl.SyclDevice`]:
+                Tuple of component devices.
 
         Raises:
             ValueError:

dpctl/_sycl_device_factory.pxd

@@ -18,7 +18,7 @@
 # cython: language_level=3
 
 """ The file declares several helper functions to create SyclDevice objects
-from SYCL standard device_selectors, to get a list of SyclDevices for a
+from SYCL standard device_selectors, to get a tuple of SyclDevices for a
 specific backend or device_type.
 """
 
@@ -31,8 +31,8 @@ cpdef SyclDevice select_accelerator_device()
 cpdef SyclDevice select_cpu_device()
 cpdef SyclDevice select_default_device()
 cpdef SyclDevice select_gpu_device()
-cpdef list get_devices(backend=*, device_type=*)
-cpdef list get_composite_devices()
+cpdef tuple get_devices(backend=*, device_type=*)
+cpdef tuple get_composite_devices()
 cpdef int get_num_devices(backend=*, device_type=*)
 cpdef cpp_bool has_gpu_devices()
 cpdef cpp_bool has_cpu_devices()

dpctl/_sycl_device_factory.pyx

@@ -22,7 +22,7 @@
 
   - wrapper functions to create a SyclDevice from the standard SYCL
     device selector classes.
-  - functions to return a list of devices based on a specified device_type or
+  - functions to return a tuple of devices based on a specified device_type or
     backend_type combination.
 """
 
@@ -133,7 +133,7 @@ cdef _device_type _enum_to_dpctl_sycl_device_ty(DTy):
         return _device_type._UNKNOWN_DEVICE
 
 
-cdef list _get_devices(DPCTLDeviceVectorRef DVRef):
+cdef tuple _get_devices(DPCTLDeviceVectorRef DVRef):
     cdef list devices = []
     cdef size_t nelems = 0
     if DVRef:
@@ -143,12 +143,14 @@ cdef list _get_devices(DPCTLDeviceVectorRef DVRef):
             D = SyclDevice._create(DRef)
             devices.append(D)
 
-    return devices
+    return tuple(devices)
 
 
-cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all):
+cpdef tuple get_devices(
+    backend=backend_type.all, device_type=device_type_t.all
+):
     """
-    Returns a list of :class:`dpctl.SyclDevice` instances selected based on
+    Returns a tuple of :class:`dpctl.SyclDevice` instances selected based on
     the given :class:`dpctl.device_type` and :class:`dpctl.backend_type` values.
 
     The function is analogous to ``sycl::devices::get_devices()``, but with an
@@ -167,15 +169,15 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all):
             "gpu", "cpu", "accelerator", or "all".
             Default: ``dpctl.device_type.all``.
     Returns:
-        list:
-            A list of available :class:`dpctl.SyclDevice` instances that
+        Tuple[:class:`dpctl.SyclDevice`]:
+            A tuple of available :class:`dpctl.SyclDevice` instances that
             satisfy the provided :class:`dpctl.backend_type` and
             :class:`dpctl.device_type` values.
     """
     cdef _backend_type BTy = _backend_type._ALL_BACKENDS
     cdef _device_type DTy = _device_type._ALL_DEVICES
     cdef DPCTLDeviceVectorRef DVRef = NULL
-    cdef list devices
+    cdef tuple devices
 
     if isinstance(backend, str):
         BTy = _string_to_dpctl_sycl_backend_ty(backend)
@@ -204,9 +206,9 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all):
     return devices
 
 
-cpdef list get_composite_devices():
+cpdef tuple get_composite_devices():
     """
-    Returns a list of the available composite :class:`dpctl.SyclDevice`
+    Returns a tuple of the available composite :class:`dpctl.SyclDevice`
     instances.
 
     Only available when `ZE_FLAT_DEVICE_HIERARCHY=COMBINED` is set in
@@ -219,11 +221,11 @@ cpdef list get_composite_devices():
     https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/experimental/sycl_ext_oneapi_composite_device.asciidoc
 
     Returns:
-        list:
-            A list of available composite :class:`dpctl.SyclDevice` instances.
+        Tuple[:class:`dpctl.SyclDevice`]:
+            A tuple of available composite :class:`dpctl.SyclDevice` instances.
     """
     cdef DPCTLDeviceVectorRef DVRef = NULL
-    cdef list composite_devices
+    cdef tuple composite_devices
 
     DVRef = DPCTLDeviceMgr_GetCompositeDevices()
     composite_devices = _get_devices(DVRef)

dpctl/_sycl_platform.pxd

@@ -45,4 +45,4 @@ cdef class SyclPlatform(_SyclPlatform):
     cdef bool equals(self, SyclPlatform)
 
 
-cpdef list get_platforms()
+cpdef tuple get_platforms()

dpctl/_sycl_platform.pyx

@@ -378,7 +378,7 @@ cdef class SyclPlatform(_SyclPlatform):
 
     def get_devices(self, device_type=device_type_t.all):
         """
-        Returns the list of :class:`dpctl.SyclDevice` objects associated with
+        Returns a tuple of :class:`dpctl.SyclDevice` objects associated with
         :class:`dpctl.SyclPlatform` instance selected based on
         the given :class:`dpctl.device_type`.
 
@@ -391,8 +391,8 @@ cdef class SyclPlatform(_SyclPlatform):
                 Default: ``dpctl.device_type.all``.
 
         Returns:
-            list:
-                A :obj:`list` of :class:`dpctl.SyclDevice` objects
+            Tuple[:class:`dpctl.SyclDevice`]:
+                A tuple of :class:`dpctl.SyclDevice` objects
                 that belong to this platform.
 
         Raises:
@@ -455,16 +455,16 @@ cdef class SyclPlatform(_SyclPlatform):
             devices.append(SyclDevice._create(DRef))
         DPCTLDeviceVector_Delete(DVRef)
 
-        return devices
+        return tuple(devices)
 
     def get_composite_devices(self):
         """
-        Returns the list of composite :class:`dpctl.SyclDevice` objects
+        Returns a tuple of composite :class:`dpctl.SyclDevice` objects
         associated with :class:`dpctl.SyclPlatform` instance.
 
         Returns:
-            list:
-                A :obj:`list` of composite :class:`dpctl.SyclDevice` objects
+            Tuple[:class:`dpctl.SyclDevice`]:
+                A tuple of composite :class:`dpctl.SyclDevice` objects
                 that belong to this platform.
 
         Raises:
@@ -487,7 +487,7 @@ cdef class SyclPlatform(_SyclPlatform):
             composite_devices.append(SyclDevice._create(DRef))
         DPCTLDeviceVector_Delete(DVRef)
 
-        return composite_devices
+        return tuple(composite_devices)
 
 
 def lsplatform(verbosity=0):
@@ -596,13 +596,13 @@ def lsplatform(verbosity=0):
     DPCTLPlatformVector_Delete(PVRef)
 
 
-cpdef list get_platforms():
+cpdef tuple get_platforms():
     """
-    Returns a list of all available SYCL platforms on the system.
+    Returns a tuple of all available SYCL platforms on the system.
 
     Returns:
-        List[:class:`.SyclPlatform`]:
-            A list of SYCL platforms on the system.
+        Tuple[:class:`.SyclPlatform`]:
+            A tuple of SYCL platforms on the system.
     """
     cdef list platforms = []
     cdef DPCTLPlatformVectorRef PVRef = NULL
@@ -617,4 +617,4 @@ cpdef list get_platforms():
             platforms.append(P)
 
     DPCTLPlatformVector_Delete(PVRef)
-    return platforms
+    return tuple(platforms)