Add linting of vtable slots compared to exports by jakelishman · Pull Request #15778 · Qiskit/qiskit

jakelishman · 2026-03-07T00:35:01Z

A risk of having the definitions of C API functions (cext) separate to the crate defining the static vtable structure (cext-vtable) is that these can more easily get out of sync. This extends the capabilities of qiskit-bindgen-c to add linting of those two crates against each other, providing a convenience wrapper (tools/check_slots.sh) to run a suitable set of checks, and enforcing this in CI.

Depends on:

Add C API vtable to pyext #15761

I will also write a follow-on linter to this that checks for ABI stability between different Qiskit versions (some of the code structure of this patch already indicates where I'm going here - I cut this patch out of a WIP commit).

This isn't a public code feature for 2.4, just an internal QA tool for developers.

qiskit-bot · 2026-03-07T00:35:06Z

One or more of the following people are relevant to this code:

@Qiskit/terra-core

jan-an

Hi Jake, thank you so much for this PR.
Looks good to me, I just have some very minor questions / comments.

jan-an · 2026-03-17T23:08:58Z

.github/workflows/lint_docs.yml

      - name: Run lint
        run: |
          make cformat
+          tools/check_slots.bash


Given that this lint check may not be relevant for every PR but only when there are changes to files such as in crates/cext or crates/cext-vtable, would it make sense to want to decouple this to have that kind of control, say such as via a dedicated lint check for C API related check that is skipped for example, on a python-changes-only sort of PR but runs when there are relevant changes?

A related comment that perhaps answers my above question. I noticed that further into the PR that we also have more changes where we have separated standalone C API exports (qiskit.h) from Python-extension-specific exports (qiskit/funcs_py.h), meaning that this lint check would need to cover a larger set of potentially modifiable files. So running it on every PR is likely the simpler and safer choice?

Your point is totally valid - ideally we'd only do differential linting - but it's pretty hard to get working reliably in practice. You really don't want false negatives in your lint/test suite, and it's very easy to accidentally introduce false negatives when we do incremental checking. It's easier to err on the safe side and just always do it - the build should not be expensive.

crates/bindgen-c/src/abi.rs

crates/bindgen-c/README.md

jan-an

Just a few more additional minor comments and suggestions correcting typos. Thank you!

jan-an · 2026-03-18T10:18:07Z

crates/cext-vtable/src/lib.rs

+    .add_child(250, &circuit_library::FUNCTIONS);
+pub static FUNCTIONS_QI: ExportedFunctions =
+    ExportedFunctions::empty().add_child(0, &sparse_observable::FUNCTIONS);
+pub use transpiler::FUNCTIONS as FUNCTIONS_TRANSPILE;


Is there a reason FUNCTIONS_TRANSPILE is re-exported as an alias whereas the others are directly declared statically?

This is actually introduced in a parent commit of this one (you've reviewed a complete changeset, not just the single change of the last commit), and I talked about it a bit more here: #15761 (comment)

crates/cext-vtable/README.md

crates/cext/src/transpiler/target.rs

qiskit/capi/__init__.py

releasenotes/notes/c-dag-getter-00bce3ca7de3b19c.yaml

releasenotes/notes/header-file-include-aad5efd67ace6bad.yaml

mrossinek

Overall this looks great. Just a few comments from my side 👍

mrossinek · 2026-03-19T08:56:28Z

crates/bindgen-c/src/abi.rs

+                ("circuit", &qiskit_cext_vtable::FUNCTIONS_CIRCUIT),
+                ("transpile", &qiskit_cext_vtable::FUNCTIONS_TRANSPILE),
+                ("qi", &qiskit_cext_vtable::FUNCTIONS_QI),


Just noting that, this hard-coded list of VTables to check against needs to be kept in sync with the root-level VTables of the crate that is being checked. While probably not ideal, this is the simplest solution for now. But this should be documented over in the cext-vtable crate accordingly.

It does, yeah. The trouble is that there are several associations of name: vtable used in various places (C header files, vtable creation, this linter, etc) and I didn't want the vtables to actually have to own them all. If we come up with something better, we can swap to it.

mrossinek · 2026-03-19T09:10:28Z

crates/bindgen-c/src/lint.rs

This is definitely beyond scope right now (i.e. for 2.4) but I think it would be great if we could add some tests to make sure that these lints actually catch the errors that they are supposed to catch.

One edge case that I have in mind immediately is for example duplicate exported functions but across different root-level vtables..

Fwiw this should work - I tested it locally and used it to catch errors - but yeah, it would be better to have tests.

crates/bindgen-c/src/main.rs

mrossinek · 2026-03-19T09:16:29Z

crates/bindgen-c/README.md

+cargo run -p qiskit-bindgen-c -- lint-slots -c crates/cext
+```
+
+This checks various coherence properties between the declared `extern "C"` functions in


What is the point of allowing --cext-path be specified from the CLI while hard-coding qiskit-cext-vtable internally?

I'm not suggesting we relax the hard-coding of the latter, just questioning the flexibility on the former instead of hard-coding that, too.

because qiskit_cext_vtable is a compiled-in dependency, so cargo arranges for it to be compiled into the binary, but cbindgen needs to be pointed at the source tree on disk to parse qiskit-cext

mrossinek · 2026-03-19T09:16:58Z

crates/bindgen-c/README.md

+all functions have a slot and there are no duplicates; in other words, that each exported function
+is referenced exactly onces.
+
+Note that this command does not test for ABI compatibility between different Qiskit versions.


Is this something you plan to be able to lint in the future?

Yes - I have half of it on a local laptop, and it's just waiting for me to finish off writing a simple diff algorithm into it and pushing it up

mrossinek · 2026-03-19T09:18:24Z

crates/bindgen-c/README.md

+
+- `no-export`: assert that the function will not be in the slots list (such as for functions
+  deprecated before the introduction of the vtables).
+- `allow-duplicates`: allow functions to be in more than one slot (if, for example, we want to


Do you have a motivation for allowing this?

Not really a useful motivation: the reason is that I have a lint that forbids you from doing it, so I also added the escape valve to bypass the lint. I don't have a use in mind for bypassing that lint.

Fair enough I suppose. Although given that you don't actually support it below, not having this bypass for the time being might be the easier fix rather than supporting it within the 2.4 time window..

crates/bindgen-c/src/lint.rs

crates/bindgen/src/lib.rs

While Qiskitgh-15778 is not yet merged, we don't have CI enforcement that the vtable slots are always completely up-to-date. Several PRs adding new C API functions merged between the merge-base of Qiskitgh-15761[^1] and `main` at its time of merge (and subsequently). This PR uses the machinery in Qiskitgh-15778 to bring the slots completely up-to-date. [^1]: 888c877: Add C API vtable to `pyext`

While gh-15778 is not yet merged, we don't have CI enforcement that the vtable slots are always completely up-to-date. Several PRs adding new C API functions merged between the merge-base of gh-15761[^1] and `main` at its time of merge (and subsequently). This PR uses the machinery in gh-15778 to bring the slots completely up-to-date. [^1]: 888c877: Add C API vtable to `pyext`

A risk of having the definitions of C API functions (`cext`) separate to the crate defining the static vtable structure (`cext-vtable`) is that these can more easily get out of sync. This extends the capabilities of `qiskit-bindgen-c` to add linting of those two crates against each other, providing a convenience wrapper (`tools/check_slots.bash`) to run a suitable set of checks, and enforcing this in CI.

Co-authored-by: Janani Ananthanarayanan <101062130+jan-an@users.noreply.github.com>

mrossinek

Nice, I like the way you went about allowing duplicates (even though we still don't have a use case for it, per se) 👍

mrossinek · 2026-03-20T09:24:11Z

crates/cext/src/transpiler/target.rs

+    // SAFETY: per documentation, we are attached to a Python interpreter, `object` points to a
+    // valid Python object and `address` points to enough space to write a pointer.


Although valid changes, these seem unrelated to this PR

They're from Janani's review above

mrossinek · 2026-03-20T09:24:41Z

releasenotes/notes/2.4/header-file-include-aad5efd67ace6bad.yaml

+    your compiler's search path using :func:`qiskit.capi.get_include`.
 build:
-  - Packages dependening on the Qiskit C API to build can now specify Qiskit as a Python-space build
+  - Packages depending on the Qiskit C API to build can now specify Qiskit as a Python-space build


Same as previous comment: relevant but unrelated

crates/bindgen-c/README.md

jan-an

Thanks for the changes Jake, LGTM 👍🏻

jan-an · 2026-03-20T13:34:20Z

Thanks for the changes Jake, LGTM 👍🏻

There seem to be a couple of failures in the CI jobs, I've re-run them just to be sure there is something needing correction.. if it fails again, maybe some minor change maybe needed to account for that

jakelishman added this to the 2.4.0 milestone Mar 7, 2026

jakelishman requested a review from a team as a code owner March 7, 2026 00:35

github-project-automation bot added this to Qiskit 2.4 Mar 7, 2026

jakelishman added Changelog: None Do not include in the GitHub Release changelog. C API Related to the C API labels Mar 7, 2026

github-project-automation bot moved this to Ready in Qiskit 2.4 Mar 7, 2026

jakelishman mentioned this pull request Mar 7, 2026

Provide a safe way for Python extension modules to use the C API #15572

Closed

jakelishman force-pushed the c/slots-lint branch from 4c429bd to c1f9165 Compare March 7, 2026 00:44

jakelishman added the type: qa Issues and PRs that relate to testing and code quality label Mar 7, 2026

alexanderivrii assigned jan-an Mar 10, 2026

jakelishman mentioned this pull request Mar 17, 2026

Add C API vtable to pyext #15761

Merged

3 tasks

jan-an reviewed Mar 17, 2026

View reviewed changes

jan-an reviewed Mar 18, 2026

View reviewed changes

mrossinek reviewed Mar 19, 2026

View reviewed changes

jakelishman mentioned this pull request Mar 19, 2026

Add cext slots added since last update #15838

Merged

jakelishman and others added 4 commits March 19, 2026 18:16

Fix typos

0b36869

Co-authored-by: Janani Ananthanarayanan <101062130+jan-an@users.noreply.github.com>

Fix macro/comment order

a767a3b

Fix allow-duplicate lint suppression

c8033da

jakelishman force-pushed the c/slots-lint branch from c1f9165 to c8033da Compare March 19, 2026 18:32

Fix legacy comment

1edadb6

mrossinek reviewed Mar 20, 2026

View reviewed changes

jakelishman added 2 commits March 20, 2026 11:08

Unify naming of allow-duplicate

96e10d5

Merge remote-tracking branch 'ibm/main' into c/slots-lint

d73bd20

jan-an reviewed Mar 20, 2026

View reviewed changes

		// SAFETY: per documentation, we are attached to a Python interpreter, `object` points to a
		// valid Python object and `address` points to enough space to write a pointer.

Conversation

jakelishman commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qiskit-bot commented Mar 7, 2026

Uh oh!

jan-an left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jan-an left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mrossinek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mrossinek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jan-an left a comment

Choose a reason for hiding this comment

Uh oh!

jan-an commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

jakelishman commented Mar 7, 2026 •

edited

Loading