[ndgrigorian]

This PR improves the pickling support in dpctl by making SyclContext, SyclDevice, and SyclQueue picklable, with the intention of making downstream projects (i.e., dpnp) that implement objects that use these objects picklable, as well

The device is restored by its filter string, the context by one of the devices, and the queue is restored by the mix of context, device, and properties. If the properties are default properties, the cached queue is used.

Note that for queues, only queues on a root device with the default context can be pickled

MemoryUSM* memory classes now also carry the queue information when pickled, and will fail to pickle with PicklingError for an unpicklable queue

Closes #1716

• Have you provided a meaningful PR description?
• Have you added a test, reproducer or referred to an issue with a reproducer?
• Have you tested your changes locally for CPU and GPU devices?
• Have you made sure that new changes do not introduce compiler warnings?
• Have you checked performance impact of proposed changes?
• Have you added documentation for your changes, if necessary?
• Have you added your changes to the changelog?
• If this PR is a work in progress, are you opening the PR as a draft?

[github-actions]

View rendered docs @ https://intelpython.github.io/dpctl/pulls/2406/index.html

[coveralls]

coverage: 74.893% (-0.1%) from 74.989% — feature/improve-pickling-support into master

[antonwolfy]

Built the PR head (96ece36) with DPC++ 2026.2 on a Panther Lake host (Arc B390, devices opencl:gpu:0, opencl:cpu:0, level_zero:gpu:0).

I checked by hand:

• context, device, queue and USM memory round-trip on every device, and a context survives a second round-trip;
• a default-property queue is restored as get_device_cached_queue(dev); an in_order queue shared by two objects in one dumps is restored as a single object; USM memory keeps in_order through pickling;
• old two-argument _to_memory pickles still load, onto the default device;
• pickle protocols 0-5 all work;
• loading in a separate process with no ONEAPI_DEVICE_SELECTOR restores the same filter strings.

Two small points are inline: the error type when the device is missing at load time, and the error message for a queue on a sub-device.

One question, which I could not test with a single GPU: the filter string's relative id is counted among the devices visible under the current ONEAPI_DEVICE_SELECTOR. With two identical GPUs, a pickle made with level_zero:1 and loaded without a selector would land on the other GPU, and the name check would not catch it, since the names match. Is that acceptable for now, maybe with a note in the docstring?

[Copilot]

🟡 Changes recommended

The test allocates every USM kind on every device without checking support, causing USMAllocationError on valid configurations before pickling is exercised.

1 open issue

• Skip devices lacking the requested USM allocation aspect · New

What changed in this PR

Adds pickling support for SYCL devices, default contexts, and eligible queues, enabling downstream objects that hold them to be serialized.

Changes:

• Adds reconstruction logic and identity-preserving copy behavior for SYCL objects.
• Preserves queue information in pickled USM memory, reusing cached queues for default properties.
• Adds round-trip, rejection, subprocess, and backward-compatibility tests.

File	Description
dpctl/​tests/​test_sycl_usm.py	Tests queue preservation and legacy memory reconstruction.
dpctl/​tests/​test_sycl_queue.py	Tests queue pickling, caching, restrictions, and copying.
dpctl/​tests/​test_sycl_device.py	Tests device reconstruction, validation, and copying.
dpctl/​tests/​test_sycl_context.py	Tests context pickling restrictions and copying.
dpctl/​tests/​helper/​_helper.py	Adds a helper for finding partitionable devices.
dpctl/​tests/​helper/​__init__.py	Exports the sub-device helper.
dpctl/​memory/​_memory.pyx	Includes queue information in memory serialization.
dpctl/​_sycl_queue.pyx	Adds queue serialization and documents reconstruction semantics.
dpctl/​_sycl_device.pyx	Adds device serialization with filter and name validation.
dpctl/​_sycl_context.pyx	Adds serialization for default root-device contexts.
CHANGELOG.md	Documents pickling and copy behavior changes.

_{Review effort: Balanced}