Skip to content

RFC: cuda.bindings: guarantee an append-only Cython (cy*) layer within a CUDA major, and check it in CI #3483

Open
0 of 1 issue completed

Description

@leofang

Projects such as CuPy, cuda-core and RAPIDS cimport the cy* modules of cuda.bindings. Each builds against its own cuda-bindings release, and in a user's environment they all share one installed cuda-bindings. That works when each project declares a floor (cuda-bindings>=<floor>,<next major>; see #3459): the environment resolves to a release at or above the highest floor, and modules built against older releases keep working, because at import Cython checks only the functions a module uses (tested with Cython 3.2.9):

  • a used function that is missing raises ImportError: ... does not export expected C function ...;
  • a used function whose argument or return types changed raises TypeError: ... has wrong signature;
  • parameter renames, removed functions that the module does not use, and except-clause changes pass. The except clause is not checked at all.

#1030 states this as the intended contract ("Projects built against cuda-bindings 12.x (via cimport) should work with all 12.y, for arbitrary x <= y"), after Cython ABI breaks in 11.x (conda-forge/cuda-python-feedstock#15) and 12.x (#274). Item 5 of the support policy (12.x, 13.x, last updated in #2977) does not promise it: "due to Cython limitations a new minor release of this module could require Cython layer users to rebuild their projects and update their pinning to this module." A downstream project that takes this at its word caps cuda-bindings at the minor it built against, and two projects built against different minors can then not be installed together.

In practice the layer is already append-only. Comparing the __pyx_capi__ capsule signatures of the cy* modules (the function check of toolshed/check_cython_abi.py, #1929) between consecutive releases from 12.9.3 to 12.9.10 and from 13.0.2 to 13.5.0, functions were only added, with two exceptions: cynvrtc dropped nvrtcGetNVVM and nvrtcGetNVVMSize in 12.9.8, and the cy_nvml preview module became cynvml in 13.2.0 when NVML was made public (#1544).

Proposal

  1. Reword item 5 in both support.rst files as the guarantee from CI: Add integration tests to cover cuda.bindings ABI stability #1030: within a CUDA major, cy* functions are only added. An existing function keeps its argument types, return type and except clause, and is not removed; such changes wait for the next major.
  2. Run toolshed/check_cython_abi.py in CI on the cy* modules against the latest release of the same major, downloading that release's wheel as the baseline instead of committing ABI files (the alternative suggested in Detect __pyx_capi__ changes in testing #1067), and fail on missing or changed symbols. This is the integration job that CI: Add integration tests to cover cuda.bindings ABI stability #1030 tracks. Two gaps to close:
    • With cuda-bindings 13.5.0 and Cython 3.2.9, the tool's .pxd struct parser fails on cydriver.pxd, cycudla.pxd and cycufile.pxd (the parse error surfaces as AttributeError: '_thread._local' object has no attribute 'cython_errors_stack'), so generate stops at the first of them.
    • Capsule signatures do not include the except clause, and Cython does not check it at import, so except changes need a separate comparison of the .pxd declarations.

-- Leo's bot

Activity

  1. self-assigned this
    on Nov 17, 2026
  2. added
    RFCPlans and announcements
    cuda.bindingsEverything related to the cuda.bindings module
    on Nov 17, 2026
  3. removed their assignment
    on Nov 17, 2026
  4. mdboom commented on Nov 17, 2026

    @mdboom
    Contributor

    Agree with all of this in principle as a reasonable goal. Details for the checking tool may need to get hammered out but should be fine in principle.

  5. added this to the cuda.bindings next milestone on Nov 17, 2026
  6. yangcal commented on Nov 17, 2026

    @yangcal
    Contributor

    RE: tooling, is it possible to build the checking tool in the generator and each project can opt in during binding generation? (I think we should develop the tool just once and shared across teams)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

RFCPlans and announcementscuda.bindingsEverything related to the cuda.bindings module

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions