Skip to content

Commit a76263c

Browse files
fedonmanAndy-Jostclaude
authored
docs(cuda.core): document PinnedMemoryResource.allocate parameters (NVIDIA#2713)
* 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 NVIDIA#2712. Signed-off-by: Vyron Vasileiadis <[email protected]> * 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 <[email protected]> --------- Signed-off-by: Vyron Vasileiadis <[email protected]> Co-authored-by: Andy Jost <[email protected]> Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent f9212dd commit a76263c

2 files changed

Lines changed: 46 additions & 2 deletions

File tree

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,29 @@ class PinnedMemoryResource(_MemPool):
8484
"""
8585
def __init__(self, options: PinnedMemoryResourceOptions | None=None) -> None: ...
8686
def allocate(self, size: int, *, stream: Stream | GraphBuilder) -> Buffer:
87-
"""Allocate a host-pinned buffer asynchronously on the supplied stream."""
87+
"""Allocate a host-pinned buffer asynchronously on the supplied stream.
88+
89+
Parameters
90+
----------
91+
size : int
92+
The size of the buffer to allocate, in bytes.
93+
stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
94+
Keyword-only. The stream on which to perform the allocation
95+
asynchronously. Must be passed explicitly; pass
96+
``device.default_stream`` to use the default stream.
97+
98+
Returns
99+
-------
100+
Buffer
101+
The allocated buffer object, which is accessible from the host.
102+
103+
Raises
104+
------
105+
RuntimeError
106+
If the stream's device does not support the requested host memory
107+
pool. Use :class:`LegacyPinnedMemoryResource` when stream-ordered
108+
allocation is not required.
109+
"""
88110
def __reduce__(self) -> tuple[object, ...]: ...
89111
@staticmethod
90112
def from_registry(uuid: uuid.UUID) -> PinnedMemoryResource:

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,29 @@ cdef class PinnedMemoryResource(_MemPool):
113113
_PMR_init(self, options)
114114

115115
def allocate(self, size_t size, *, stream: Stream | GraphBuilder) -> Buffer:
116-
"""Allocate a host-pinned buffer asynchronously on the supplied stream."""
116+
"""Allocate a host-pinned buffer asynchronously on the supplied stream.
117+
118+
Parameters
119+
----------
120+
size : int
121+
The size of the buffer to allocate, in bytes.
122+
stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
123+
Keyword-only. The stream on which to perform the allocation
124+
asynchronously. Must be passed explicitly; pass
125+
``device.default_stream`` to use the default stream.
126+
127+
Returns
128+
-------
129+
Buffer
130+
The allocated buffer object, which is accessible from the host.
131+
132+
Raises
133+
------
134+
RuntimeError
135+
If the stream's device does not support the requested host memory
136+
pool. Use :class:`LegacyPinnedMemoryResource` when stream-ordered
137+
allocation is not required.
138+
"""
117139
MP_check_open(self)
118140
if self.is_mapped:
119141
raise TypeError("Cannot allocate from a mapped IPC-enabled memory resource")

0 commit comments

Comments
 (0)