Skip to content

docs(core): drop incorrect handle_type requirement for cuMemRetainAllocationHandle#2418

Open
aryanputta wants to merge 1 commit into
NVIDIA:mainfrom
aryanputta:fix/vmm-handle-type-docstring
Open

docs(core): drop incorrect handle_type requirement for cuMemRetainAllocationHandle#2418
aryanputta wants to merge 1 commit into
NVIDIA:mainfrom
aryanputta:fix/vmm-handle-type-docstring

Conversation

@aryanputta

Copy link
Copy Markdown
Contributor

Addresses defect 4 of #2388.

The handle_type entry on VirtualMemoryResourceOptions told users that "posix_fd" is "required for cuMemRetainAllocationHandle". The precondition as written is wrong, on two independent pieces of evidence in this repo:

  • The shipped driver documentation for cuMemRetainAllocationHandle (cuda_bindings/cuda/bindings/driver.pyx) states only that the address must have been previously mapped by cuMemMap. It places no requirement on the allocation's export handle type.
  • VirtualMemoryResource.deallocate calls cuMemRetainAllocationHandle(ptr) unconditionally, under raise_if_driver_error, on every buffer it frees. If an exportable POSIX file descriptor were genuinely required, closing any handle_type=None buffer would raise, and it does not.

The cost of the sentence is that it steers users into requesting an exportable handle they do not need, which constrains the allocation for no benefit.

To be careful about what is being claimed: the clause may have been shorthand for the fact that you need an exportable handle to do something useful with a retained allocation across processes. That is a different and defensible statement, but it is not what the docstring said, so this removes the incorrect precondition rather than asserting that handle types are irrelevant to IPC.

Scope: the rest of the entry is accurate and is kept, so this removes the parenthetical and reflows the three lines it left ragged. One thing I noticed and deliberately did not touch is that handle_type already defaults to VirtualMemoryHandleType.POSIX_FD, which makes the surviving "use posix_fd if you plan to import/export" advice read a little oddly against its own default. That is a pre-existing wording question rather than a correctness one, and rewriting the whole entry felt like scope creep on a defect-4 fix. Happy to fold it in here if you would prefer.

No behavior change and no rendered API-surface change, so no release note.

The other defects in #2388 are not covered here. Defect 2 is #2407. Defects 1 and 3 overlap the Transaction rework in #2235 and the guard restructure in #2237, so I am holding those until those two land rather than building on a moving target.

I cannot set a label or milestone as an outside contributor, so pr-metadata-check will be red until a maintainer applies them. documentation plus cuda.core next look right.

…ocationHandle

Defect 4 of NVIDIA#2388.

Signed-off-by: Aryan <aryansputta@gmail.com>
@copy-pr-bot

copy-pr-bot Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

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.

@github-actions github-actions Bot added the cuda.core Everything related to the cuda.core module label Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cuda.core Everything related to the cuda.core module

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant