Skip to content

fix(cuda.core): pickle memory-resource devices by UUID for IPC - #3126

Open
Andy-Jost wants to merge 3 commits into
NVIDIA:mainfrom
Andy-Jost:ajost/ipc-pickle-device-uuid
Open

Andy-Jost wants to merge 3 commits into
NVIDIA:mainfrom
Andy-Jost:ajost/ipc-pickle-device-uuid

Conversation

@Andy-Jost

Copy link
Copy Markdown
Contributor

Summary

A DeviceMemoryResource sent through multiprocessing, and a pickled VirtualMemoryResource, named their device by ordinal, and the VirtualMemoryResource also sent its peers as ordinals. Device ordinals are per process, so a receiver with a different CUDA_VISIBLE_DEVICES rebuilt the resource on the wrong GPU, or granted peer access to the wrong GPU and only faulted later. This PR sends the owning device and the peers by UUID and maps them back in the receiving process.

Changes

  • _device.pyx: new private helper _device_from_uuid() that scans the visible devices once and raises a RuntimeError naming the missing UUID and the visible devices when nothing matches.
  • _device_memory_resource.pyx: the multiprocessing reducer sends (type, device UUID, allocation handle) and rebuilds through from_allocation_handle() on the receiver's device with that UUID.
  • _virtual_memory_resource.pyx: __reduce__ sends the owner UUID (None for host-located memory), the peer UUIDs, and the options without peers; the receiver rebuilds with its own ordinals.
  • Docstrings, the .pyi stubs, and a 1.3.0 release-note entry.
  • New tests/memory_ipc/test_device_uuid.py: the child process sees the two GPUs in reversed order through a UUID-form CUDA_VISIBLE_DEVICES, and asserts that the imported buffer's device has the parent's UUID, for pool-backed buffers, VMM buffers, and a VMM resource with peers. A negative test hides the owning GPU and checks the error. The tests need two visible devices and skip otherwise.

Device.__reduce__ still pickles the ordinal. Changing it would alter behavior for code that sends a Device to mean "this ordinal", so it is left for a separate decision.

Testing

Validated on a two-GPU Linux host: the memory IPC suite plus test_memory.py pass, including the five new tests.

Related Work

Closes #3097. Follow-up to #3028 (reported in review there by @juenglin and @brandon-b-miller).

🤖 Generated with Claude Code

Andy-Jost and others added 3 commits October 15, 2026 14:54
A DeviceMemoryResource sent through multiprocessing, and a pickled
VirtualMemoryResource, named their device by ordinal, and the
VirtualMemoryResource also sent its peers as ordinals. Ordinals are per
process, so a receiver with a different CUDA_VISIBLE_DEVICES rebuilt the
resource on the wrong GPU or granted peer access to the wrong GPU.

Send the owner and the peers by UUID and map them back in the receiver
with a new private helper. Raise a clear RuntimeError when no visible
device has the UUID. The tests reverse the device order in the child
through CUDA_VISIBLE_DEVICES and check the imported buffer's device UUID.

Closes NVIDIA#3097

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The check-cython-not-none hook from main requires it on a def parameter
annotated with a cdef class.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Andy-Jost Andy-Jost added this to the cuda.core 1.3.0 milestone Oct 15, 2026
@Andy-Jost Andy-Jost added bug Something isn't working P1 Medium priority - Should do cuda.core Everything related to the cuda.core module labels Oct 15, 2026
@Andy-Jost Andy-Jost self-assigned this Oct 15, 2026
@coderabbitai

coderabbitai Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

📝 Summary

Summary by CodeRabbit

  • New Features
    • Multiprocessing memory resources now match devices by UUID, so they remain associated with the same physical device even when device ordinals differ between processes.
    • Virtual memory resources preserve their device and peer-device associations when transferred between processes.
  • Bug Fixes
    • Receiving a resource now raises a clear error if its associated device isn’t visible in the receiving process.

Device-memory and virtual-memory IPC serialization now identifies devices by UUID. Receiving processes resolve those UUIDs to local device ordinals. Reconstruction raises RuntimeError when a referenced device is not visible.

Changes: IPC UUID mapping

Layer / File(s) Summary
Device lookup and memory-resource reconstruction
cuda_core/cuda/core/_device.pyi, cuda_core/cuda/core/_device.pyx, cuda_core/cuda/core/_memory/_device_memory_resource.pyi, cuda_core/cuda/core/_memory/_device_memory_resource.pyx, cuda_core/tests/memory_ipc/test_device_uuid.py
_device_from_uuid resolves a UUID among visible devices. Device-memory resource pickling stores the device UUID and allocation handle, then resolves the UUID during reconstruction. Tests cover reordered device visibility and missing owner devices.
Virtual-memory owner and peer reconstruction
cuda_core/cuda/core/_memory/_virtual_memory_resource.pyi, cuda_core/cuda/core/_memory/_virtual_memory_resource.pyx, cuda_core/docs/source/release/1.3.0-notes.rst, cuda_core/tests/memory_ipc/test_device_uuid.py
Virtual-memory resource pickling stores the owner and peer UUIDs. Reconstruction maps them to local ordinals and restores peer configuration. Tests check owner identity, peer identity, access flags, and missing devices.

Assessment against linked issues

Objective Addressed Explanation
Pickle owner devices and virtual-memory peers by UUID, map them to receiving-process ordinals, and report an error when a UUID is not visible [#3097] ✅

Suggested reviewers: mdboom

Priority: ➖ Normal

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: 🔵 Low · up to 160a2

Buffer transfers configured with generator-supplied peers can lose peer access in the receiving process. This is a bounded issue that should be fixed or explicitly accepted before merge.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration
  • Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: 72c7d735-1982-4195-8b61-d8894498ad10
📥 Commits

Reviewing files that changed from the base of the PR and between 2224499 and 160a21c.

📒 Files selected for processing: 8
  • cuda_core/cuda/core/_device.pyi
  • cuda_core/cuda/core/_device.pyx
  • cuda_core/cuda/core/_memory/_device_memory_resource.pyi
  • cuda_core/cuda/core/_memory/_device_memory_resource.pyx
  • cuda_core/cuda/core/_memory/_virtual_memory_resource.pyi
  • cuda_core/cuda/core/_memory/_virtual_memory_resource.pyx
  • cuda_core/docs/source/release/1.3.0-notes.rst
  • cuda_core/tests/memory_ipc/test_device_uuid.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

# Device ordinals are per process, so the owning device and the peers
# travel by UUID and the receiver maps them to its own devices.
owner_uuid = self.device.uuid if self.device is not None else None
peer_uuids = tuple(Device(peer).uuid for peer in self.config.peers)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

important: Preserve peers from one-shot iterables.

If VirtualMemoryResourceOptions.peers is a generator, allocation consumes it in _fill_access. A later buffer pickle serializes no peer UUIDs. The receiving resource then omits access for a peer that could access the exported buffer. Store peers as a reusable tuple when the resource accepts its configuration, and test a buffer transfer with generator-supplied peers.

@github-actions

Copy link
Copy Markdown
Contributor

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working cuda.core Everything related to the cuda.core module P1 Medium priority - Should do

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cuda.core: IPC pickling rebuilds memory resources with the sender's device indices

1 participant