Skip to content

Disable annotation_typing - #2902

Open
mdboom wants to merge 3 commits into
NVIDIA:mainfrom
mdboom:annotation-typing
Open

mdboom wants to merge 3 commits into
NVIDIA:mainfrom
mdboom:annotation-typing

Conversation

@mdboom

@mdboom mdboom commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

A possible implementation of #2894.

This should give us something to discuss -- about whether this is an improvement or not.

My 2c -- keeping "semantically meaningful typing" separate from "annotation-only typing" has some upsides, but it creates additional redundancy that could be confusing.

As an aside, this did identify a few places where runtime type checking is performed multiple times unnecessarily, and in any event we should fix that.

@copy-pr-bot

copy-pr-bot Bot commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

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 Sep 17, 2026
@mdboom

mdboom commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test

@github-actions

Copy link
Copy Markdown
Contributor

@mdboom

mdboom commented Sep 18, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test

Comment thread cuda_core/build_hooks.py
"embedsignature": True,
"warn.deprecated.IF": False,
"freethreading_compatible": True,
"annotation_typing": False,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️

@leofang

leofang commented Oct 6, 2026

Copy link
Copy Markdown
Member

@mdboom we should discuss this. I am huge +1 in merging this.

@mdboom mdboom added the PR review get-together Mark PRs you'd like the team to review at the weekly PR review get-together. label Oct 6, 2026
@mdboom

mdboom commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

/ok to merge e04d1b9

@mdboom

mdboom commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

The one thing I don't like (but could live with) is under this flag we have to do:

Device dev: Device (saying Device twice). The first affects runtime behavior and causes the argument to be type-checked. The second is emitted in the docs as so:

image

That all makes sense when we don't want them to match, but when we do, it seems like it would be easy to forget the second one.

@rparolin rparolin added this to the cuda.core next milestone Oct 8, 2026
@leofang

leofang commented Oct 9, 2026

Copy link
Copy Markdown
Member

As we discussed on Slack a while ago, I think it's the right way to go with

def foo(T bar: T): ...

and I am +1 to move on. The first T is for Cython and the second T is for Python. With cdef classes, they happen to have the same name, as per Cython's design.

cc @Andy-Jost for vis/blessing

@mdboom
mdboom marked this pull request as ready for review October 12, 2026 15:53
@coderabbitai

coderabbitai Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

📝 Summary

Summary by CodeRabbit

  • Bug Fixes

    • Context switching now routes a context to its owning device and handles same-device switches directly, while continuing to return the previous context.
  • Refactor

    • CUDA operations involving devices, streams, memory, kernels, events, and graphs now handle their expected object types more consistently. No other behavior changes are noted.

Walkthrough

The change sets a Cython compiler directive and updates typed argument declarations across CUDA core, memory, graph, and system APIs. Device.set_current also changes how it switches contexts and returns the previous context.

Changes

CUDA Core API and Context Updates

Layer / File(s) Summary
Annotation typing policy
cuda_core/build_hooks.py, cuda_core/cuda/core/_context.pyx, cuda_core/cuda/core/_memory/*_memory_resource.pyx
The build directives now set annotation_typing=False. Local decorators and related imports are removed from context and memory-resource code.
Device context handling
cuda_core/cuda/core/_device.pyx
Device memory-resource and context parameters use Cython types. Device.set_current delegates contexts owned by another device, directly replaces the current same-device driver context, and returns the previous context when available.
Execution and module argument types
cuda_core/cuda/core/_event.pyx, cuda_core/cuda/core/_launcher.pyx, cuda_core/cuda/core/_layout.pyx, cuda_core/cuda/core/_module.pyx, cuda_core/cuda/core/_stream.pyx, cuda_core/cuda/core/_tensor_bridge.pyx
These APIs declare typed arguments directly. Several call sites no longer use explicit casts.
Memory and peer-access argument types
cuda_core/cuda/core/_memory/_buffer.pyx, cuda_core/cuda/core/_memory/_copy_ops.pyx, cuda_core/cuda/core/_memory/_peer_access_utils.*
Buffer, stream, and memory-resource arguments use Cython types. Peer-access helpers use the typed resource directly.
Graph and system argument types
cuda_core/cuda/core/graph/*, cuda_core/cuda/core/system/*
Graph methods use Cython-typed arguments. System device parameters use Cython declarations, and collection indexes use Py_ssize_t.

Suggested reviewers: andy-jost


Priority: ➖ Normal

Change: Refactor

Merge Risk: 🟠 High · up to e04d1

Creating a stream with an explicit context now fails, which breaks a core workflow. Passing None as a graph kernel or as a system device can crash at the native level instead of raising a clear argument error. Fix these issues before merging.

✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Commit to this branch
  • Create a new PR

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3


ℹ️ Review info
⚙️ Run configuration
  • Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: 798365be-b1a0-4b10-94b2-999dde12bee0
📥 Commits

Reviewing files that changed from the base of the PR and between 5078fe6 and e04d1b9.

📒 Files selected for processing (21)
  • cuda_core/build_hooks.py
  • cuda_core/cuda/core/_context.pyx
  • cuda_core/cuda/core/_device.pyx
  • cuda_core/cuda/core/_event.pyx
  • cuda_core/cuda/core/_launcher.pyx
  • cuda_core/cuda/core/_layout.pyx
  • cuda_core/cuda/core/_memory/_buffer.pyx
  • cuda_core/cuda/core/_memory/_copy_ops.pyx
  • cuda_core/cuda/core/_memory/_device_memory_resource.pyx
  • cuda_core/cuda/core/_memory/_managed_memory_resource.pyx
  • cuda_core/cuda/core/_memory/_peer_access_utils.pyi
  • cuda_core/cuda/core/_memory/_peer_access_utils.pyx
  • cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx
  • cuda_core/cuda/core/_module.pyx
  • cuda_core/cuda/core/_stream.pyx
  • cuda_core/cuda/core/_tensor_bridge.pyx
  • cuda_core/cuda/core/graph/_graph_node.pyx
  • cuda_core/cuda/core/graph/_subclasses.pyx
  • cuda_core/cuda/core/system/_device.pyx
  • cuda_core/cuda/core/system/_field_values.pxi
  • cuda_core/cuda/core/system/_system_events.pyx
💤 Files with no reviewable changes (4)
  • cuda_core/cuda/core/_memory/_managed_memory_resource.pyx
  • cuda_core/cuda/core/_memory/_pinned_memory_resource.pyx
  • cuda_core/cuda/core/_memory/_device_memory_resource.pyx
  • cuda_core/cuda/core/_context.pyx

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

@cython.annotation_typing(False)
def _init(cls, obj: IsStreamType | None = None, options: StreamOptions | None = None,
device_id: int | None = None, ctx: Context | None = None) -> Stream:
device_id: int | None = None, Context ctx: Context | None = None) -> Stream:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

important: Replace the remaining context reference with ctx.

The removed local variable leaves context.is_green at Line 175 unresolved. When _init creates a stream with a context, that check raises NameError before create_stream_handle runs. Use ctx.is_green there. Cython resolves names by scope and can fall back to Python lookup for an unresolved name. (cython.readthedocs.io)

s.update(value)

def launch(self, config: LaunchConfig, kernel: Kernel, *args) -> KernelNode:
def launch(self, config: LaunchConfig, Kernel kernel: Kernel, *args) -> KernelNode:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

important: Reject None before the kernel handle access. A Cython-typed Kernel argument accepts None. If a caller passes None, GN_launch reads ker._h_kernel without a null check. Require a non-None kernel at this public entrypoint to preserve a safe argument error. (cython.readthedocs.io)



def get_topology_common_ancestor(device1: Device, device2: Device) -> GpuTopologyLevel:
def get_topology_common_ancestor(Device device1: Device, Device device2: Device) -> GpuTopologyLevel:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

important: Reject None before accessing NVML device handles. Cython-typed Device arguments accept None. Both public functions then read _handle without a null check, so a None argument can fail at the C-attribute access. (cython.readthedocs.io)

  • cuda_core/cuda/core/system/_device.pyx#L1113-L1113: validate both devices before get_topology_common_ancestor reads their handles.
  • cuda_core/cuda/core/system/_device.pyx#L1139-L1139: validate both devices before get_p2p_status reads their handles.
📍 Affects 1 file
  • cuda_core/cuda/core/system/_device.pyx#L1113-L1113 (this comment)
  • cuda_core/cuda/core/system/_device.pyx#L1139-L1139

@Andy-Jost
Andy-Jost self-requested a review October 12, 2026 18:55

@Andy-Jost Andy-Jost left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The direction looks good, but two things need fixing first:

  1. The build fails: _stream.pyx:175 uses context, which this PR removes. #2920 added that use on main, and the merge of main brought it in without a conflict. Use ctx.
  2. With annotation typing, arg: T rejects None when T is a cdef class. With this change, T arg: T accepts None, and an annotation-only arg: T accepts anything. Where the code then reaches C, None crashes instead of raising TypeError. CodeRabbit flagged three cases, but the same pattern appears in more than twenty public entry points, including launch, the GraphNode builders, the update methods and Buffer.copy_from.

It looks like we need the following:

  • Write T arg not None: T where Cython knows T, and arg not None: T where it does not. Keep T | None where None is valid.
  • Add a pre-commit check that rejects a def parameter annotated with a single cdef class unless it has a not None clause or its annotation includes None.
  • Add a few tests that pass None to launch, GraphNode.launch and Buffer.copy_from, and expect a TypeError.

This branch has not been deployed

No deployments
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 PR review get-together Mark PRs you'd like the team to review at the weekly PR review get-together.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants