Skip to content

Commit f9212dd

Browse files
Andy-Jostclaude
andauthored
refactor(cuda.core): rename VirtualMemoryIPCBufferDescriptor to VirtualMemoryFdBufferDescriptor (#3229)
The class carries POSIX file descriptors for VirtualMemoryResource buffers. A fabric-handle descriptor will sit beside it, so its name now says which transport it is. No alias: the class first appears in the unreleased 1.3.0. No behavior change. Written by Codex (gpt-6.1-sol); reviewed by Claude. Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent 20a4aee commit f9212dd

9 files changed

Lines changed: 31 additions & 31 deletions

File tree

‎cuda_core/cuda/core/_cpp/rt/VMM_DESIGN.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,7 +259,7 @@ descriptor either; it records only that it was imported (`is_mapped`). A
259259
descriptor parked in a `Queue` or sent to a `Pool` pins the memory in the
260260
sender until the receiver unpickles it. Besides `multiprocessing`, a process
261261
with its own file descriptor passing sends the descriptor's `fds`, `sizes`,
262-
and `size` and rebuilds it with `VirtualMemoryIPCBufferDescriptor.from_fds()`,
262+
and `size` and rebuilds it with `VirtualMemoryFdBufferDescriptor.from_fds()`,
263263
which duplicates the integers it is given and always builds a `posix_fd`
264264
descriptor.
265265

@@ -304,7 +304,7 @@ importer needs access to the exporter's IMEX channel rather than a matching
304304
device index, and the memory may live on another node. The file-descriptor
305305
rules above (ownership, pinning, `pickle` raising, the same-device check) do
306306
not hold for it, so fabric sharing gets a descriptor class of its own instead
307-
of a widened `VirtualMemoryIPCBufferDescriptor`, whose `handles` stay
307+
of a widened `VirtualMemoryFdBufferDescriptor`, whose `handles` stay
308308
`IPCAllocationHandle`s. `from_fds()` is POSIX-only by construction for the
309309
same reason and takes no handle type; a fabric descriptor is plain data and
310310
needs no out-of-band constructor. Tracked on the VMM epic (#2980).

‎cuda_core/cuda/core/_memory/_ipc.pxd‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ cdef class IPCAllocationHandle:
5555

5656
# Descriptor of a VirtualMemoryResource buffer: one exported handle per
5757
# physical allocation that backs the buffer, in address order.
58-
cdef class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
58+
cdef class VirtualMemoryFdBufferDescriptor(IPCBufferDescriptor):
5959
cdef readonly int _handle_type
6060
cdef readonly tuple _chunk_sizes
6161
cdef readonly tuple _handles

‎cuda_core/cuda/core/_memory/_ipc.pyi‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ class IPCAllocationHandle:
5858
@property
5959
def uuid(self) -> uuid.UUID: ...
6060

61-
class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
61+
class VirtualMemoryFdBufferDescriptor(IPCBufferDescriptor):
6262
"""Serializable object describing a :class:`VirtualMemoryBuffer` that can be shared between processes.
6363
6464
The descriptor holds one exported POSIX file descriptor per physical
@@ -97,9 +97,9 @@ class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
9797
_handles: tuple[Any, ...]
9898

9999
@staticmethod
100-
def _from_exports(handle_type: int, chunk_sizes: tuple[int, ...], handles: tuple[Any, ...], size: int) -> VirtualMemoryIPCBufferDescriptor: ...
100+
def _from_exports(handle_type: int, chunk_sizes: tuple[int, ...], handles: tuple[Any, ...], size: int) -> VirtualMemoryFdBufferDescriptor: ...
101101
@classmethod
102-
def from_fds(cls, fds: Iterable[int | IPCAllocationHandle], sizes: Iterable[int], *, size: int | None=None) -> VirtualMemoryIPCBufferDescriptor:
102+
def from_fds(cls, fds: Iterable[int | IPCAllocationHandle], sizes: Iterable[int], *, size: int | None=None) -> VirtualMemoryFdBufferDescriptor:
103103
"""Build a descriptor from POSIX file descriptors received outside ``multiprocessing``.
104104
105105
The exporter sends ``fds``, ``sizes``, and ``size`` of its descriptor

‎cuda_core/cuda/core/_memory/_ipc.pyx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ def _reconstruct_allocation_handle(cls: type, df: object, uuid: uuid.UUID | None
177177
multiprocessing.reduction.register(IPCAllocationHandle, _reduce_allocation_handle)
178178

179179

180-
cdef class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
180+
cdef class VirtualMemoryFdBufferDescriptor(IPCBufferDescriptor):
181181
"""Serializable object describing a :class:`VirtualMemoryBuffer` that can be shared between processes.
182182
183183
The descriptor holds one exported POSIX file descriptor per physical
@@ -215,9 +215,9 @@ cdef class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
215215
@staticmethod
216216
def _from_exports(
217217
handle_type: int, chunk_sizes: tuple[int, ...], handles: tuple, size: int
218-
) -> VirtualMemoryIPCBufferDescriptor:
219-
cdef VirtualMemoryIPCBufferDescriptor self = VirtualMemoryIPCBufferDescriptor.__new__(
220-
VirtualMemoryIPCBufferDescriptor)
218+
) -> VirtualMemoryFdBufferDescriptor:
219+
cdef VirtualMemoryFdBufferDescriptor self = VirtualMemoryFdBufferDescriptor.__new__(
220+
VirtualMemoryFdBufferDescriptor)
221221
self._payload = b""
222222
self._size = size
223223
self._handle_type = handle_type
@@ -232,7 +232,7 @@ cdef class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
232232
sizes: Iterable[int],
233233
*,
234234
size: int | None = None,
235-
) -> VirtualMemoryIPCBufferDescriptor:
235+
) -> VirtualMemoryFdBufferDescriptor:
236236
"""Build a descriptor from POSIX file descriptors received outside ``multiprocessing``.
237237

238238
The exporter sends ``fds``, ``sizes``, and ``size`` of its descriptor
@@ -292,7 +292,7 @@ cdef class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
292292
raise
293293
# The handle owns the duplicate now; if append fails, the handle closes it once.
294294
handles.append(handle)
295-
return VirtualMemoryIPCBufferDescriptor._from_exports(driver_type, sizes_t, tuple(handles), size)
295+
return VirtualMemoryFdBufferDescriptor._from_exports(driver_type, sizes_t, tuple(handles), size)
296296

297297
@property
298298
def handle_type(self) -> VirtualMemoryHandleType:
@@ -330,7 +330,7 @@ cdef class VirtualMemoryIPCBufferDescriptor(IPCBufferDescriptor):
330330

331331
def __reduce__(self) -> tuple[object, ...]:
332332
# multiprocessing duplicates the IPCAllocationHandle fds into the receiver; plain pickle raises.
333-
return VirtualMemoryIPCBufferDescriptor._from_exports, (
333+
return VirtualMemoryFdBufferDescriptor._from_exports, (
334334
self._handle_type, self._chunk_sizes, self._handles, self._size)
335335

336336

@@ -359,7 +359,7 @@ cdef Buffer Buffer_from_ipc_descriptor(
359359
cls, object mr, IPCBufferDescriptor ipc_descriptor, stream
360360
):
361361
"""Import a buffer that was exported from another process."""
362-
if isinstance(ipc_descriptor, VirtualMemoryIPCBufferDescriptor):
362+
if isinstance(ipc_descriptor, VirtualMemoryFdBufferDescriptor):
363363
# Imported here rather than cimported: _virtual_memory_resource
364364
# cimports this module.
365365
from cuda.core._memory._virtual_memory_resource import VirtualMemoryResource

‎cuda_core/cuda/core/_memory/_virtual_memory_resource.pyi‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ from typing import Iterable
66

77
from cuda.core._device import Device
88
from cuda.core._memory._buffer import Buffer, MemoryResource
9-
from cuda.core._memory._ipc import VirtualMemoryIPCBufferDescriptor
9+
from cuda.core._memory._ipc import VirtualMemoryFdBufferDescriptor
1010
from cuda.core._stream import Stream
1111
from cuda.core._utils.cuda_utils import driver
1212
from cuda.core.graph import GraphBuilder
@@ -98,7 +98,7 @@ class VirtualMemoryBuffer(Buffer):
9898
freed when the last buffer that maps it closes.
9999
"""
100100
@property
101-
def ipc_descriptor(self) -> VirtualMemoryIPCBufferDescriptor:
101+
def ipc_descriptor(self) -> VirtualMemoryFdBufferDescriptor:
102102
"""A new descriptor for sharing this buffer with other processes.
103103
104104
Every access exports the physical allocations that back the buffer
@@ -205,7 +205,7 @@ class VirtualMemoryResource(MemoryResource):
205205
is not visible. Plain ``pickle`` cannot carry the file descriptors; a
206206
process with its own file descriptor passing sends the descriptor's
207207
``fds``, ``sizes``, and ``size`` and rebuilds it with
208-
``VirtualMemoryIPCBufferDescriptor.from_fds()``. The importing resource
208+
``VirtualMemoryFdBufferDescriptor.from_fds()``. The importing resource
209209
maps the memory for its device and the devices in its ``peers`` option,
210210
with its own access options. A descriptor pins the physical memory while
211211
it exists, in every process that holds one, and nothing else does. A
@@ -346,7 +346,7 @@ class VirtualMemoryResource(MemoryResource):
346346
(``location_type`` ``"host"``, ``"host_numa"``, or
347347
``"host_numa_current"``) is not shared yet.
348348
"""
349-
def _import_ipc_buffer(self, desc: VirtualMemoryIPCBufferDescriptor, stream) -> VirtualMemoryBuffer:
349+
def _import_ipc_buffer(self, desc: VirtualMemoryFdBufferDescriptor, stream) -> VirtualMemoryBuffer:
350350
"""Import a buffer that another process exported; see :meth:`Buffer.from_ipc_descriptor`.
351351
352352
Every exported allocation is imported with this resource's handle

‎cuda_core/cuda/core/_memory/_virtual_memory_resource.pyx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ from cuda.core._memory._buffer cimport (
1818
from cuda.core._memory._ipc cimport (
1919
IPCAllocationHandle,
2020
IPCDataForBuffer,
21-
VirtualMemoryIPCBufferDescriptor,
21+
VirtualMemoryFdBufferDescriptor,
2222
)
2323
from cuda.core._rt cimport (
2424
ContextHandle,
@@ -296,7 +296,7 @@ cdef class VirtualMemoryBuffer(Buffer):
296296
"""
297297

298298
@property
299-
def ipc_descriptor(self) -> VirtualMemoryIPCBufferDescriptor:
299+
def ipc_descriptor(self) -> VirtualMemoryFdBufferDescriptor:
300300
"""A new descriptor for sharing this buffer with other processes.
301301

302302
Every access exports the physical allocations that back the buffer
@@ -439,7 +439,7 @@ cdef class VirtualMemoryResource(MemoryResource):
439439
is not visible. Plain ``pickle`` cannot carry the file descriptors; a
440440
process with its own file descriptor passing sends the descriptor's
441441
``fds``, ``sizes``, and ``size`` and rebuilds it with
442-
``VirtualMemoryIPCBufferDescriptor.from_fds()``. The importing resource
442+
``VirtualMemoryFdBufferDescriptor.from_fds()``. The importing resource
443443
maps the memory for its device and the devices in its ``peers`` option,
444444
with its own access options. A descriptor pins the physical memory while
445445
it exists, in every process that holds one, and nothing else does. A
@@ -916,7 +916,7 @@ cdef class VirtualMemoryResource(MemoryResource):
916916
and self.config.location_type not in _HOST_LOCATION_TYPES
917917
)
918918
919-
def _import_ipc_buffer(self, VirtualMemoryIPCBufferDescriptor desc not None, stream) -> VirtualMemoryBuffer:
919+
def _import_ipc_buffer(self, VirtualMemoryFdBufferDescriptor desc not None, stream) -> VirtualMemoryBuffer:
920920
"""Import a buffer that another process exported; see :meth:`Buffer.from_ipc_descriptor`.
921921

922922
Every exported allocation is imported with this resource's handle
@@ -1092,7 +1092,7 @@ def _reconstruct_virtual_memory_resource(
10921092
return cls(device, replace(config, peers=peers))
10931093

10941094

1095-
cdef VirtualMemoryIPCBufferDescriptor _export_ipc_descriptor(Buffer buf):
1095+
cdef VirtualMemoryFdBufferDescriptor _export_ipc_descriptor(Buffer buf):
10961096
"""Export the allocations that back ``buf`` as shareable handles, in address order.
10971097
10981098
Only the allocations that cover ``buf.size`` are exported; a buffer's size
@@ -1154,4 +1154,4 @@ cdef VirtualMemoryIPCBufferDescriptor _export_ipc_descriptor(Buffer buf):
11541154
# The handle owns the fd now; if append fails, the handle closes it once.
11551155
handles.append(handle)
11561156
sizes.append(chunk)
1157-
return VirtualMemoryIPCBufferDescriptor._from_exports(handle_type, tuple(sizes), tuple(handles), buf._size)
1157+
return VirtualMemoryFdBufferDescriptor._from_exports(handle_type, tuple(sizes), tuple(handles), buf._size)

‎cuda_core/docs/source/api_private.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ CUDA runtime
4848
_device.DeviceProperties
4949
_memory._ipc.IPCAllocationHandle
5050
_memory._ipc.IPCBufferDescriptor
51-
_memory._ipc.VirtualMemoryIPCBufferDescriptor
51+
_memory._ipc.VirtualMemoryFdBufferDescriptor
5252
_memory._managed_buffer.AccessedBySetProxy
5353

5454

‎cuda_core/docs/source/release/1.3.0-notes.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ New features
9797
physical allocation and pins the memory while it exists; nothing else does.
9898
A buffer that contains imported memory cannot be exported again. For a
9999
transport of your own, the descriptor exposes ``fds``, ``sizes``, and
100-
``size``, and ``VirtualMemoryIPCBufferDescriptor.from_fds()`` rebuilds it
100+
``size``, and ``VirtualMemoryFdBufferDescriptor.from_fds()`` rebuilds it
101101
in the receiver. Fabric handles are not shared yet.
102102
(`#2980 <https://github.com/NVIDIA/cuda-python/issues/2980>`__)
103103

‎cuda_core/tests/memory_ipc/test_vmm_ipc.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
from cuda.bindings import driver
3131
from cuda.core import Buffer, Device, MemoryResource, VirtualMemoryResource, VirtualMemoryResourceOptions
3232
from cuda.core._dlpack import DLDeviceType
33-
from cuda.core._memory._ipc import IPCAllocationHandle, IPCBufferDescriptor, VirtualMemoryIPCBufferDescriptor
33+
from cuda.core._memory._ipc import IPCAllocationHandle, IPCBufferDescriptor, VirtualMemoryFdBufferDescriptor
3434
from cuda.core._memory._virtual_memory_resource import VirtualMemoryBuffer
3535
from cuda.core._utils.cuda_utils import CUDAError, handle_return
3636
from cuda.core.utils import StridedMemoryView
@@ -113,7 +113,7 @@ def _forge(desc, **fields):
113113
fields.setdefault("chunk_sizes", desc._chunk_sizes)
114114
fields.setdefault("handles", desc._handles)
115115
fields.setdefault("size", desc.size)
116-
return VirtualMemoryIPCBufferDescriptor._from_exports(
116+
return VirtualMemoryFdBufferDescriptor._from_exports(
117117
fields["handle_type"], fields["chunk_sizes"], fields["handles"], fields["size"]
118118
)
119119

@@ -812,7 +812,7 @@ def test_round_trip_with_os_dup(self, vmm_ipc_device):
812812
del desc
813813
gc.collect()
814814
assert _open_fds() == fds0 + 2
815-
rebuilt = VirtualMemoryIPCBufferDescriptor.from_fds(wire["fds"], wire["sizes"], size=wire["size"])
815+
rebuilt = VirtualMemoryFdBufferDescriptor.from_fds(wire["fds"], wire["sizes"], size=wire["size"])
816816
assert _open_fds() == fds0 + 4, "from_fds duplicates the integers it is given"
817817
for fd in wire["fds"]:
818818
os.close(fd) # the caller keeps ownership of its own
@@ -838,7 +838,7 @@ def test_from_fds_shares_handle_objects_and_rejects_bad_input(self, vmm_ipc_devi
838838
buf = mr.allocate(1)
839839
gran = buf.size
840840
desc = buf.ipc_descriptor
841-
from_fds = VirtualMemoryIPCBufferDescriptor.from_fds
841+
from_fds = VirtualMemoryFdBufferDescriptor.from_fds
842842

843843
shared = from_fds(desc.handles, desc.sizes)
844844
assert shared.handles[0] is desc.handles[0] # an IPCAllocationHandle is shared, not duplicated
@@ -898,7 +898,7 @@ def child_main(device_id, sock, queue):
898898
with sock:
899899
msg, fds, _flags, _addr = socket.recv_fds(sock, 4096, 16)
900900
header = json.loads(msg)
901-
desc = VirtualMemoryIPCBufferDescriptor.from_fds(fds, header["sizes"], size=header["size"])
901+
desc = VirtualMemoryFdBufferDescriptor.from_fds(fds, header["sizes"], size=header["size"])
902902
for fd in fds:
903903
os.close(fd) # from_fds duplicated them; the received ones are ours to close
904904
imported = Buffer.from_ipc_descriptor(_resource(device), desc, stream=device.default_stream)

0 commit comments

Comments
 (0)