From d8ba7baf4758037b8b2ae98f75c9504ca4939c8f Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Thu, 27 Aug 2026 23:46:06 +0300 Subject: [PATCH 1/2] docs(cuda.core): document PinnedMemoryResource.allocate parameters The override's one-line docstring is what autodoc renders, so the generated page for the public class documented neither the required keyword-only stream argument nor the return value, and never mentioned the RuntimeError raised when the device does not support the requested host memory pool. Give the override the full numpydoc body. The .pyi stub is regenerated by the stubgen-pyx-cuda-core pre-commit hook. Closes #2712. Signed-off-by: Vyron Vasileiadis --- .../core/_memory/_pinned_memory_resource.pyi | 25 ++++++++++++++++++- .../core/_memory/_pinned_memory_resource.pyx | 25 ++++++++++++++++++- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi index 76a7010dbc4..64790815fbc 100644 --- a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi +++ b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi @@ -84,7 +84,30 @@ class PinnedMemoryResource(_MemPool): """ def __init__(self, options: PinnedMemoryResourceOptions | None=None) -> None: ... def allocate(self, size: int, *, stream: Stream | GraphBuilder) -> Buffer: - """Allocate a host-pinned buffer asynchronously on the supplied stream.""" + """Allocate a host-pinned buffer asynchronously on the supplied stream. + + Parameters + ---------- + size : int + The size of the buffer to allocate, in bytes. + stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder` + Keyword-only. The stream on which to perform the allocation + asynchronously. Must be passed explicitly; pass + ``device.default_stream`` to use the default stream. + + Returns + ------- + Buffer + The allocated buffer object, which is accessible from the host and + from the device that the stream belongs to. + + Raises + ------ + RuntimeError + If the stream's device does not support the requested host memory + pool. Use :class:`LegacyPinnedMemoryResource` when stream-ordered + allocation is not required. + """ def __reduce__(self) -> tuple[object, ...]: ... @staticmethod def from_registry(uuid: uuid.UUID) -> PinnedMemoryResource: diff --git a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx index 8fe06a254e6..b13ce8fc185 100644 --- a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx +++ b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx @@ -113,7 +113,30 @@ cdef class PinnedMemoryResource(_MemPool): _PMR_init(self, options) def allocate(self, size_t size, *, stream: Stream | GraphBuilder) -> Buffer: - """Allocate a host-pinned buffer asynchronously on the supplied stream.""" + """Allocate a host-pinned buffer asynchronously on the supplied stream. + + Parameters + ---------- + size : int + The size of the buffer to allocate, in bytes. + stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder` + Keyword-only. The stream on which to perform the allocation + asynchronously. Must be passed explicitly; pass + ``device.default_stream`` to use the default stream. + + Returns + ------- + Buffer + The allocated buffer object, which is accessible from the host and + from the device that the stream belongs to. + + Raises + ------ + RuntimeError + If the stream's device does not support the requested host memory + pool. Use :class:`LegacyPinnedMemoryResource` when stream-ordered + allocation is not required. + """ MP_check_open(self) if self.is_mapped: raise TypeError("Cannot allocate from a mapped IPC-enabled memory resource") From fc1d65707a1538409892b227e2dc82ed019be556 Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Mon, 26 Oct 2026 10:38:56 +0200 Subject: [PATCH 2/2] docs(cuda.core): drop device-access claim from PinnedMemoryResource.allocate The Returns text said the buffer is accessible from the device that the stream belongs to. PinnedMemoryResource creates its pool from CUmemPoolProps alone and never calls cuMemPoolSetAccess, and the driver documents host-located pools as accessible from the host CPU by default, so only the host access is established. Signed-off-by: Vyron Vasileiadis --- cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi | 3 +-- cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi index e462a75ca1c..258a39eeaa7 100644 --- a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi +++ b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi @@ -98,8 +98,7 @@ class PinnedMemoryResource(_MemPool): Returns ------- Buffer - The allocated buffer object, which is accessible from the host and - from the device that the stream belongs to. + The allocated buffer object, which is accessible from the host. Raises ------ diff --git a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx index b13ce8fc185..5762c940301 100644 --- a/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx +++ b/cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx @@ -127,8 +127,7 @@ cdef class PinnedMemoryResource(_MemPool): Returns ------- Buffer - The allocated buffer object, which is accessible from the host and - from the device that the stream belongs to. + The allocated buffer object, which is accessible from the host. Raises ------