Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions cuda_core/cuda/core/_memory/_pinned_memory_resource.pxd
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ from cuda.core._memory._memory_pool cimport _MemPool

cdef class PinnedMemoryResource(_MemPool):
cdef int _numa_id
# False only for an imported pool whose node is unknown (see numa_id).
cdef bint _numa_id_known
22 changes: 18 additions & 4 deletions cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ class PinnedMemoryResource(_MemPool):
If the memory resource already has a different UUID.
"""
@classmethod
def from_allocation_handle(cls, alloc_handle: int | IPCAllocationHandle) -> PinnedMemoryResource:
def from_allocation_handle(cls, alloc_handle: int | IPCAllocationHandle, numa_id: int | None=None) -> PinnedMemoryResource:
"""Create a host-pinned memory resource from an allocation handle.

Construct a new `PinnedMemoryResource` instance that imports a memory
Expand All @@ -159,6 +159,14 @@ class PinnedMemoryResource(_MemPool):
The shareable handle of the host-pinned memory resource to import. If an
integer is supplied, it must represent a valid platform-specific
handle. It is the caller's responsibility to close that handle.
numa_id : int | None, optional
The host NUMA node the exporting process placed the pool on, that
is, the exporting resource's :attr:`numa_id`. Node IDs are the same
in every process on the host. The pool's node is read from the
driver when possible (a CUDA 13 build of ``cuda.core`` and a 13.2
or later driver); otherwise this value is the imported resource's
:attr:`numa_id`. Unpickling a resource passes the exporter's node
automatically. Must be >= 0 if given.

Returns
-------
Expand All @@ -172,6 +180,10 @@ class PinnedMemoryResource(_MemPool):
The pool's kind is checked with a CUDA 13 build of ``cuda.core``
and a 13.2 or later driver. Otherwise it is checked only when the
handle's memory resource is already registered in this process.
ValueError
If ``numa_id`` is negative, or differs from the node of the pool,
as reported by the driver or by the resource already registered in
this process for the handle.
"""
@property
def allocation_handle(self) -> IPCAllocationHandle:
Expand All @@ -188,9 +200,11 @@ class PinnedMemoryResource(_MemPool):
"""The host NUMA node ID used for pool placement, or -1 for OS-managed placement.

For a resource imported with :meth:`from_allocation_handle`, this is the
pool's node only if the pool's location can be queried (a CUDA 13 build
of ``cuda.core`` and a 13.2 or later driver). Otherwise it is 0, which is
not known to be the pool's node.
pool's node if the pool's location can be queried (a CUDA 13 build of
``cuda.core`` and a 13.2 or later driver), if the caller passed
``numa_id`` to :meth:`from_allocation_handle`, or if the resource was
unpickled from a resource whose node was known. Otherwise it is 0, which
is not known to be the pool's node.
"""
@property
def is_device_accessible(self) -> bool:
Expand Down
61 changes: 51 additions & 10 deletions cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ cdef class PinnedMemoryResource(_MemPool):

@classmethod
def from_allocation_handle(
cls, alloc_handle: int | IPCAllocationHandle
cls, alloc_handle: int | IPCAllocationHandle, numa_id: int | None = None
) -> PinnedMemoryResource:
"""Create a host-pinned memory resource from an allocation handle.

Expand All @@ -213,6 +213,14 @@ cdef class PinnedMemoryResource(_MemPool):
The shareable handle of the host-pinned memory resource to import. If an
integer is supplied, it must represent a valid platform-specific
handle. It is the caller's responsibility to close that handle.
numa_id : int | None, optional
The host NUMA node the exporting process placed the pool on, that
is, the exporting resource's :attr:`numa_id`. Node IDs are the same
in every process on the host. The pool's node is read from the
driver when possible (a CUDA 13 build of ``cuda.core`` and a 13.2
or later driver); otherwise this value is the imported resource's
:attr:`numa_id`. Unpickling a resource passes the exporter's node
automatically. Must be >= 0 if given.

Returns
-------
Expand All @@ -226,16 +234,27 @@ cdef class PinnedMemoryResource(_MemPool):
The pool's kind is checked with a CUDA 13 build of ``cuda.core``
and a 13.2 or later driver. Otherwise it is checked only when the
handle's memory resource is already registered in this process.
ValueError
If ``numa_id`` is negative, or differs from the node of the pool,
as reported by the driver or by the resource already registered in
this process for the handle.
"""
if numa_id is not None and numa_id < 0:
raise ValueError(f"numa_id must be >= 0, got {numa_id}")

# cuMemPoolImportFromShareableHandle requires CUDA to be initialized, but in
# a child process CUDA may not be initialized yet. For DeviceMemoryResource,
# this is not a concern because most likely when retrieving the device_id the
# user would have already initialized CUDA. But since PinnedMemoryResource is
# not device-specific it is unlikelt the case.
HANDLE_RETURN(cydriver.cuInit(0))

return <PinnedMemoryResource>(
_ipc.MP_from_allocation_handle(cls, alloc_handle, _PMR_init_imported))
cdef PinnedMemoryResource mr = <PinnedMemoryResource>(
_ipc.MP_from_allocation_handle(cls, alloc_handle, _PMR_init_imported, numa_id))
# The import hook does not run for a resource that is already registered,
# whether found at the start or registered by a concurrent import.
_PMR_check_numa_id(mr, numa_id)
return mr

@property
def allocation_handle(self) -> IPCAllocationHandle:
Expand All @@ -259,9 +278,11 @@ cdef class PinnedMemoryResource(_MemPool):
"""The host NUMA node ID used for pool placement, or -1 for OS-managed placement.

For a resource imported with :meth:`from_allocation_handle`, this is the
pool's node only if the pool's location can be queried (a CUDA 13 build
of ``cuda.core`` and a 13.2 or later driver). Otherwise it is 0, which is
not known to be the pool's node.
pool's node if the pool's location can be queried (a CUDA 13 build of
``cuda.core`` and a 13.2 or later driver), if the caller passed
``numa_id`` to :meth:`from_allocation_handle`, or if the resource was
unpickled from a resource whose node was known. Otherwise it is 0, which
is not known to be the pool's node.
"""
return self._numa_id

Expand Down Expand Up @@ -322,6 +343,7 @@ cdef inline _PMR_init(PinnedMemoryResource self, options):
loc_type = cydriver.CUmemLocationType.CU_MEM_LOCATION_TYPE_HOST

self._numa_id = numa_id
self._numa_id_known = True

if opts is None:
MP_init_current_pool(
Expand Down Expand Up @@ -365,23 +387,42 @@ cdef inline int _PMR_grant_device_access(
return 0


cdef int _PMR_init_imported(_MemPool mr, object unused) except? -1:
cdef inline int _PMR_check_numa_id(PinnedMemoryResource self, object numa_id) except? -1:
# A node the caller passed must agree with a node that is known.
if numa_id is not None and self._numa_id_known and self._numa_id != numa_id:
raise ValueError(
f"numa_id {numa_id} does not match the NUMA node of the memory pool, "
f"which is {self._numa_id}")
return 0


cdef int _PMR_init_imported(_MemPool mr, object numa_id) except? -1:
cdef PinnedMemoryResource self = <PinnedMemoryResource>mr
cdef cydriver.CUmemLocation loc
# IPC-enabled pinned pools created by cuda.core are always placed on a host
# NUMA node. Without a location query (a CUDA 12 build or a driver before
# 13.2), the pool's kind is not checked and numa_id keeps its default.
# 13.2), the pool's kind is not checked and the node is the one the caller
# passed, if any. Otherwise it is unknown and numa_id keeps its default.
cdef bint host_numa = True
if _ipc.MP_check_import_location(self, True, &loc):
host_numa = loc.type == cydriver.CUmemLocationType.CU_MEM_LOCATION_TYPE_HOST_NUMA
self._numa_id = loc.id if host_numa else -1
self._numa_id_known = True
_PMR_check_numa_id(self, numa_id)
elif numa_id is not None:
self._numa_id = numa_id
self._numa_id_known = True
return _PMR_grant_device_access(self, host_numa, True)


def _deep_reduce_pinned_memory_resource(mr: object) -> tuple[object, ...]:
check_multiprocessing_start_method()
alloc_handle = mr.allocation_handle
return mr.from_allocation_handle, (alloc_handle,)
cdef PinnedMemoryResource pmr = <PinnedMemoryResource>mr
alloc_handle = pmr.allocation_handle
# NUMA node IDs are the same in every process on the host, so the node needs
# no translation as a device ordinal does. An unknown node is not sent, so
# that the importer does not mistake the default 0 for the pool's node.
return pmr.from_allocation_handle, (alloc_handle, pmr._numa_id if pmr._numa_id_known else None)


multiprocessing.reduction.register(PinnedMemoryResource, _deep_reduce_pinned_memory_resource)
11 changes: 11 additions & 0 deletions cuda_core/docs/source/release/1.4.0-notes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,14 @@ Fixes and enhancements
later driver; with a CUDA 12 build or an older driver, imports behave as
before.
(`#3502 <https://github.com/NVIDIA/cuda-python/issues/3502>`__)

- An imported :class:`PinnedMemoryResource` reports the exporting resource's
NUMA node as ``numa_id`` also with a CUDA 12 build of ``cuda.core`` or a
driver before 13.2, where the pool's node cannot be queried. Unpickling a
resource now carries the node, and
:meth:`PinnedMemoryResource.from_allocation_handle` accepts an optional
``numa_id`` argument for a raw allocation handle. Without it, an import that
cannot query the node still reports 0, which is not known to be the pool's
node. ``from_allocation_handle`` raises ``ValueError`` for a negative
``numa_id`` or one that differs from the pool's known node.
(`#3508 <https://github.com/NVIDIA/cuda-python/issues/3508>`__)
133 changes: 133 additions & 0 deletions cuda_core/tests/memory_ipc/test_ipc_pool_kind.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
)
from cuda.core._memory import _memory_pool
from cuda.core._memory._buffer import _live_owned_mempool_count
from cuda.core._memory._pinned_memory_resource import _deep_reduce_pinned_memory_resource

NBYTES = 64

Expand Down Expand Up @@ -129,6 +130,93 @@ def child_imported_numa_id(alloc_handle, numa_id):
mr.close()


def child_unpickled_numa_id(mr, numa_id):
# The resource was unpickled while the child's arguments were loaded.
assert mr.numa_id == numa_id
mr.close()


def _without_location_query():
# Stand in for a 13.0 or 13.1 driver (see child_import_without_location_query).
_memory_pool.driver_version = lambda: (13, 1, 0)


# A node that the tests cannot confuse with the default of 0. Without a location
# query nothing checks it against the pool.
CLAIMED_NUMA_ID = 7


def child_import_with_numa_id_without_location_query(alloc_handle):
_without_location_query()
Device().set_current()

# A raw file descriptor carries no UUID, so each import is a separate resource.
omitted = PinnedMemoryResource.from_allocation_handle(int(alloc_handle))
assert omitted.numa_id == 0
given = PinnedMemoryResource.from_allocation_handle(int(alloc_handle), numa_id=CLAIMED_NUMA_ID)
assert given.numa_id == CLAIMED_NUMA_ID
given.close()
omitted.close()


def child_import_reduced_args_without_location_query(reduced_args):
_without_location_query()
Device().set_current()
mr = PinnedMemoryResource.from_allocation_handle(*reduced_args)
assert mr.numa_id == reduced_args[1]
mr.close()


def child_reduce_imported_resource(alloc_handle):
_without_location_query()
Device().set_current()

# The node of this import is unknown, so a third process must not be told 0.
unknown = PinnedMemoryResource.from_allocation_handle(int(alloc_handle))
assert unknown.numa_id == 0
assert _deep_reduce_pinned_memory_resource(unknown)[1][1] is None

known = PinnedMemoryResource.from_allocation_handle(int(alloc_handle), numa_id=CLAIMED_NUMA_ID)
assert _deep_reduce_pinned_memory_resource(known)[1][1] == CLAIMED_NUMA_ID
known.close()
unknown.close()


def child_registered_import_rejects_conflicting_numa_id(alloc_handle):
_without_location_query()
Device().set_current()
baseline = _live_owned_mempool_count()

mr = PinnedMemoryResource.from_allocation_handle(alloc_handle, numa_id=CLAIMED_NUMA_ID)
# The handle's UUID is now registered, so the resource is returned as is.
assert PinnedMemoryResource.from_allocation_handle(alloc_handle, numa_id=CLAIMED_NUMA_ID) is mr
with pytest.raises(ValueError, match="numa_id"):
PinnedMemoryResource.from_allocation_handle(alloc_handle, numa_id=CLAIMED_NUMA_ID + 1)
assert PinnedMemoryResource.from_allocation_handle(alloc_handle) is mr
assert mr.numa_id == CLAIMED_NUMA_ID

mr.close()
assert _live_owned_mempool_count() == baseline


def child_numa_id_is_checked_against_driver(alloc_handle):
Device().set_current()
baseline = _live_owned_mempool_count()

mr = PinnedMemoryResource.from_allocation_handle(int(alloc_handle))
node = mr.numa_id
# Releasing the rejected import cannot raise; a failed cuMemPoolDestroy
# surfaces only as a CUDAWarning.
with assert_no_cuda_warning(), pytest.raises(ValueError, match="numa_id"):
PinnedMemoryResource.from_allocation_handle(int(alloc_handle), numa_id=node + 1)

matching = PinnedMemoryResource.from_allocation_handle(int(alloc_handle), numa_id=node)
assert matching.numa_id == node
matching.close()
mr.close()
assert _live_owned_mempool_count() == baseline


def child_matching_import(mr_type, alloc_handle, descriptor):
device = Device()
device.set_current()
Expand Down Expand Up @@ -182,6 +270,15 @@ def _set_start_method(self):
with contextlib.suppress(RuntimeError):
mp.set_start_method("spawn", force=True)

@pytest.fixture
def pinned_ipc_resource(self, ipc_device):
skip_if_host_numa_pinned_memory_unsupported(ipc_device)
ipc_device.set_current()
mr = PinnedMemoryResource(PinnedMemoryResourceOptions(max_size=POOL_SIZE, ipc_enabled=True))
yield mr
mr.close()
ipc_device.sync()

@pytest.fixture
def pool_resource(self, ipc_memory_resource):
if not is_pool_resource(ipc_memory_resource):
Expand Down Expand Up @@ -261,5 +358,41 @@ def test_imported_pinned_resource_reports_numa_id(self, ipc_device):
try:
assert mr.numa_id == numa_id
run_child(child_imported_numa_id, mr.allocation_handle, numa_id)
# Unpickling the resource is the other import path.
run_child(child_unpickled_numa_id, mr, numa_id)
finally:
mr.close()

@pytest.mark.agent_authored(model="claude-sonnet-5-5")
def test_numa_id_is_checked_against_driver(self, pinned_ipc_resource):
run_child(child_numa_id_is_checked_against_driver, pinned_ipc_resource.allocation_handle)


class TestPinnedImportNumaId(_IpcPoolFixtures):
"""Without a location query, an imported pinned pool's node comes from the caller or the pickle (#3508)."""

@pytest.mark.agent_authored(model="claude-sonnet-5-5")
def test_import_uses_given_numa_id(self, pinned_ipc_resource):
run_child(child_import_with_numa_id_without_location_query, pinned_ipc_resource.allocation_handle)

@pytest.mark.agent_authored(model="claude-sonnet-5-5")
def test_pickle_carries_numa_id(self, pinned_ipc_resource):
_, reduced_args = _deep_reduce_pinned_memory_resource(pinned_ipc_resource)
assert reduced_args[0] is pinned_ipc_resource.allocation_handle
assert reduced_args[1] == pinned_ipc_resource.numa_id
run_child(child_import_reduced_args_without_location_query, reduced_args)

@pytest.mark.agent_authored(model="claude-sonnet-5-5")
def test_pickle_omits_unknown_numa_id(self, pinned_ipc_resource):
run_child(child_reduce_imported_resource, pinned_ipc_resource.allocation_handle)

@pytest.mark.agent_authored(model="claude-sonnet-5-5")
def test_registered_import_rejects_conflicting_numa_id(self, pinned_ipc_resource):
run_child(child_registered_import_rejects_conflicting_numa_id, pinned_ipc_resource.allocation_handle)

@pytest.mark.agent_authored(model="claude-sonnet-5-5")
@pytest.mark.parametrize("numa_id", [-1, -5])
def test_negative_numa_id_raises(self, numa_id):
# Rejected before the handle is used or CUDA is initialized.
with pytest.raises(ValueError, match="numa_id"):
PinnedMemoryResource.from_allocation_handle(0, numa_id=numa_id)
Loading