From d8ba7baf4758037b8b2ae98f75c9504ca4939c8f Mon Sep 17 00:00:00 2001 From: Vyron Vasileiadis Date: Thu, 27 Aug 2026 23:46:06 +0300 Subject: [PATCH] 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")