address pickling review feedback

Raise UnpicklingError when the pickled device is not available, and name
the queue in PicklingError for sub-device and non-default-context queues.
Document that filter string ids depend on ONEAPI_DEVICE_SELECTOR.

Author: ndgrigorian

dpctl/_sycl_device.pyx

@@ -376,10 +376,15 @@ def _rebuild_device(str filter_string, str name):
     """Unpickles a :class:`dpctl.SyclDevice`.
 
     Raises:
-        pickle.UnpicklingError: if the device selected by ``filter_string``
-            is not named ``name``.
+        pickle.UnpicklingError: if no device matches ``filter_string``, or
+            the device it selects is not named ``name``.
     """
-    dev = SyclDevice(filter_string)
+    try:
+        dev = SyclDevice(filter_string)
+    except SyclDeviceCreationError as e:
+        raise pickle.UnpicklingError(
+            f"Device '{filter_string}' ('{name}') is not available"
+        ) from e
     if dev.name != name:
         raise pickle.UnpicklingError(
             f"Device '{filter_string}' is '{dev.name}', expected '{name}'"
@@ -1671,6 +1676,11 @@ cdef class SyclDevice(_SyclDevice):
     def __reduce__(self):
         """Pickles a root device by its filter string and name.
 
+        The filter string's device id is relative to the devices visible
+        under ``ONEAPI_DEVICE_SELECTOR``. If the loading process sees a
+        different set of devices, the pickle may load onto another device
+        of the same name.
+
         Raises:
             pickle.PicklingError: if the device is not a root device.
         """

dpctl/_sycl_queue.pyx

@@ -23,6 +23,7 @@
 """
 
 from ._backend cimport (  # noqa: E211
+    DPCTLContext_AreEq,
     DPCTLContext_Create,
     DPCTLContext_Delete,
     DPCTLDefaultSelector_Create,
@@ -103,6 +104,7 @@ from libc.stdlib cimport free, malloc
 
 import collections.abc
 import logging
+import pickle
 import struct
 import sys
 
@@ -2221,9 +2223,26 @@ cdef class SyclQueue(_SyclQueue):
         """Pickles the queue's context, device, and properties.
 
         Raises:
-            pickle.PicklingError: if the queue's context is not the default
-                context of its device, or the device is not a root device.
+            pickle.PicklingError: if the queue's device is not a root device,
+                or its context is not the default context of that device.
         """
+        cdef DPCTLSyclContextRef CRef = NULL
+        cdef bint is_default_ctx = False
+        if self._device.parent_device is not None:
+            raise pickle.PicklingError(
+                f"Cannot pickle {self!r}: its device is not a root device"
+            )
+        CRef = DPCTLDeviceMgr_GetCachedContext(self._device.get_device_ref())
+        if CRef is not NULL:
+            is_default_ctx = DPCTLContext_AreEq(
+                CRef, self._context.get_context_ref()
+            )
+            DPCTLContext_Delete(CRef)
+        if not is_default_ctx:
+            raise pickle.PicklingError(
+                f"Cannot pickle {self!r}: its context is not the default "
+                "context of its device"
+            )
         props = []
         if DPCTLQueue_IsInOrder(self._queue_ref):
             props.append("in_order")

dpctl/tests/test_sycl_device.py

@@ -487,6 +487,13 @@ def test_device_unpickling_name_mismatch():
         _rebuild_device(dev.filter_string, dev.name + " (other)")
 
 
+def test_device_unpickling_missing_device():
+    from dpctl._sycl_device import _rebuild_device
+
+    with pytest.raises(pickle.UnpicklingError, match="is not available"):
+        _rebuild_device("opencl:gpu:999", "Missing device")
+
+
 def test_device_copy():
     sub_dev = get_sub_device_or_skip()
     root_dev = sub_dev.parent_device

dpctl/tests/test_sycl_queue.py

@@ -452,14 +452,14 @@ def test_queue_pickling_non_default_context():
     ctx = dpctl.SyclContext([dev])
     if ctx == q.sycl_context:
         pytest.skip("Context created from device list is the default context")
-    with pytest.raises(pickle.PicklingError):
+    with pytest.raises(pickle.PicklingError, match="SyclQueue.*context"):
         pickle.dumps(dpctl.SyclQueue(ctx, dev))
 
 
 def test_queue_pickling_sub_device():
     sub_dev = get_sub_device_or_skip()
     q = dpctl.SyclQueue(sub_dev)
-    with pytest.raises(pickle.PicklingError):
+    with pytest.raises(pickle.PicklingError, match="not a root device"):
         pickle.dumps(q)
 
 

dpctl/tests/test_sycl_usm.py

@@ -229,7 +229,7 @@ def test_pickling_non_default_context(memory_ctor):
     if ctx == dpctl.SyclContext(dev):
         pytest.skip("Context created from device list is the default context")
     mobj = memory_ctor(64, queue=dpctl.SyclQueue(ctx, dev))
-    with pytest.raises(pickle.PicklingError):
+    with pytest.raises(pickle.PicklingError, match="SyclQueue"):
         pickle.dumps(mobj)