docs(cuda.core): document PinnedMemoryResource.allocate parameters by fedonman · Pull Request #2713 · NVIDIA/cuda-python

fedonman · 2026-08-27T20:50:29Z

Description

PinnedMemoryResource.allocate overrides the inherited method with a one-line docstring, and that one line is all autodoc has to render, 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. This gives the override the full numpydoc body, including a Raises section for that error. The .pyi stub is regenerated by the stubgen-pyx-cuda-core pre-commit hook rather than hand-edited.

Docstring-only change, so there is no new test. What the class now renders, and the existing suite:

$ python check.py
'stream :' in rendered docstring: True
'Returns' in rendered docstring: True
'Raises' in rendered docstring: True

$ python -m pytest tests/test_memory.py -q -p no:randomly
256 passed, 15 skipped in 10.65s

No release note: the one-line docstring landed in #2487, after the cuda-core-v1.1.1 tag, so nothing user-visible changed since the last release.

Checklist

New or existing tests cover these changes.
The documentation is up to date with these changes.

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 <hi@fedonman.com>

copy-pr-bot · 2026-08-27T20:50:32Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Andy-Jost · 2026-10-23T18:03:23Z

/ok to test 3626c66

Andy-Jost

Thank you for this PR, and sorry for the eight-week wait. The expanded docstring is a clear improvement, and the Parameters and Raises sections match the implementation. One sentence needs a change before merge.

cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx, line 132: the Returns text says the buffer is accessible "from the device that the stream belongs to". The implementation does not establish that. PinnedMemoryResource creates its pool with CUmemPoolProps only and never calls cuMemPoolSetAccess, and the CUDA Driver API documentation for cuMemPoolCreate says that pools created with CU_MEM_LOCATION_TYPE_HOST or CU_MEM_LOCATION_TYPE_HOST_NUMA are accessible from the host CPU by default. Please drop the clause after "accessible from the host" (the attached suggestion does that), and regenerate the .pyi stub so the two stay in sync.

Whether PinnedMemoryResource.is_device_accessible is right without a cuMemPoolSetAccess call is a separate question. I will track it in its own issue. It does not block this PR.

I am adding the labels and milestone and starting CI now. After the edit, CI runs once more, and I merge when it is green.

Andy-Jost · 2026-10-23T18:03:58Z

+            The allocated buffer object, which is accessible from the host and
+            from the device that the stream belongs to.


Suggested change

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.

Thanks for the review! Done.

github-actions · 2026-10-23T18:25:27Z

Doc Preview CI
Preview removed because the pull request was closed or merged.

…(cuDSS 1.0 library names) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Andy-Jost · 2026-10-23T21:08:38Z

I merged main into this branch to pick up #3188 (cuDSS 1.0 library names), which the pathfinder CI step needs now. No other change. CI runs again on the new head.

Andy-Jost · 2026-10-23T21:08:40Z

/ok to test 0b5bfa3

coderabbitai · 2026-10-23T21:11:11Z

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration

Source mode: Auto
Repository: NVIDIA/cuda-python
Branch: main
File: .coderabbit.yaml
Commit: 590a8bf
Layers: Repository YAML
Review profile: CHILL
Plan: Enterprise
Run ID: 2661da12-b581-4116-b438-e5e5ff00e92a

Commits

Reviewing files that changed from the base of the PR and between fc1d657 and eb4f272.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: NVIDIA/cuda-python
Branch: main
File: .coderabbit.yaml
Commit: d5f37e0
Layers: Repository YAML
Review profile: CHILL
Plan: Advanced
Run ID: d378a9b9-df53-46aa-b55e-f8ffcf3ba3aa

Commits

Reviewing files that changed from the base of the PR and between 0b5bfa3 and fc1d657.

Files selected for processing: 2

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

Files skipped from review as they are similar to previous changes: 1

cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Summary

Summary by CodeRabbit

Documentation
- Expanded the pinned memory allocation documentation with parameter and return-value descriptions.
- Documented that allocation raises a runtime error for unsupported host memory pools.
- Added guidance to use the legacy pinned memory resource when stream-ordered allocation is not needed.
- No public declarations or allocation behavior changed.

PinnedMemoryResource.allocate now documents its parameters, return value, unsupported-pool RuntimeError condition, and an alternative resource.

Changes: Pinned allocation documentation

Layer / File(s)	Summary
Document the allocate contract `cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx`, `cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi`	The docstrings describe the required `stream` argument, returned `Buffer`, unsupported-pool `RuntimeError`, and alternative resource. The method declaration and implementation are unchanged.

Assessment against linked issues

Objective	Addressed	Explanation
Document the required `stream` argument, return value, and unsupported-pool `RuntimeError` for `PinnedMemoryResource.allocate` [`#2712`]	✅

Possibly related issues

NVIDIA/cuda-python#2795: The docstring describes the unsupported-pool error path that this issue reports can incorrectly reject supported HOST_NUMA pools. The PR does not change that behavior.
NVIDIA/cuda-python#3205: This issue concerns the device-accessibility contract for pinned buffers, which is related to the documented Buffer return.

Possibly related PRs

NVIDIA/cuda-python#3034: The release-note gate may apply to the .pyx and .pyi changes; the supplied context does not confirm the outcome.
NVIDIA/cuda-python#3209: This PR and the current PR both edit the pinned memory resource stub header, so their merge order may affect whether regeneration is needed.

Suggested reviewers: uday1o1

Priority: Low

Change: Other · Severity of issue fixed: Low

Merge Risk: Minimal · previous review fc1d6

The documentation-only change is ready to merge.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

…llocate 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 <hi@fedonman.com>

Andy-Jost · 2026-10-26T21:03:44Z

/ok to test fc1d657

Andy-Jost · 2026-10-27T15:59:31Z

/ok to test eb4f272

Removed preview folders for the following PRs: - PR #2713 - PR #3128 - PR #3149 - PR #3229 - PR #3244 - PR #3248 - PR #3249 - PR #3255

github-actions Bot added the cuda.core Everything related to the cuda.core module label Aug 27, 2026

Merge branch 'main' into docs-pinned-mr-allocate-params

3626c66

Andy-Jost added documentation Improvements or additions to documentation P1 Medium priority - Should do labels Oct 23, 2026

Andy-Jost assigned fedonman Oct 23, 2026

Andy-Jost added this to the cuda.core 1.3.0 milestone Oct 23, 2026

Andy-Jost requested changes Oct 23, 2026

View reviewed changes

Andy-Jost self-assigned this Oct 23, 2026

Andy-Jost mentioned this pull request Oct 23, 2026

cuda.core: PinnedMemoryResource.is_device_accessible returns True without granting device access to the pool #3205

Open

Merge main into docs-pinned-mr-allocate-params to pick up NVIDIA#3188 …

0b5bfa3

…(cuDSS 1.0 library names) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Andy-Jost approved these changes Oct 26, 2026

View reviewed changes

Andy-Jost enabled auto-merge (squash) October 26, 2026 20:21

Merge branch 'main' into docs-pinned-mr-allocate-params

eb4f272

Andy-Jost merged commit a76263c into NVIDIA:main Oct 27, 2026
217 of 219 checks passed

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

Clean up PR preview folders for 8 closed/merged PRs

8f5e83b

Removed preview folders for the following PRs: - PR #2713 - PR #3128 - PR #3149 - PR #3229 - PR #3244 - PR #3248 - PR #3249 - PR #3255

		The allocated buffer object, which is accessible from the host and
		from the device that the stream belongs to.

Conversation

fedonman commented Aug 27, 2026

Description

Checklist

Uh oh!

copy-pr-bot Bot commented Aug 27, 2026

Uh oh!

Andy-Jost commented Oct 23, 2026

Uh oh!

Andy-Jost left a comment

Choose a reason for hiding this comment

Uh oh!

Andy-Jost Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

fedonman Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Andy-Jost commented Oct 23, 2026

Uh oh!

Andy-Jost commented Oct 23, 2026

Uh oh!

coderabbitai Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Summary by CodeRabbit

Assessment against linked issues

Uh oh!

Andy-Jost commented Oct 26, 2026

Uh oh!

Andy-Jost commented Oct 27, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Oct 23, 2026 •

edited

Loading

coderabbitai Bot commented Oct 23, 2026 •

edited

Loading