Add runtime-version checking qk_api_version (#15831)

* Add runtime-version checking `qk_api_version`

We currently have `QISKIT_VERSION_HEX` as a macro, which allows
programmatically querying the version of the header files used at build
time.  `qk_api_version` provides the equivalent information for the
_library_ version at runtime.  This can differ in the case of dynamic
linkage, either by regular means or by the manual means in Python
extension modules.

I wanted to squeeze this into the 2.4 release because it means that safe
dynamic-linkage version checking will be available in _every_ version of
the C API that practically supports it, including in Python extensions.
For aesthetic reasons, I wanted this function (which may become part of
the `qk_import` handshake one day) to get a slot at offset 0.

* Use the heathen form of hexadecimals

Co-authored-by: Max Rossmannek <21973473+mrossinek@users.noreply.github.com>

* Handle beta versions completely

---------

Co-authored-by: Max Rossmannek <21973473+mrossinek@users.noreply.github.com>

Author: jakelishman

crates/cext-vtable/src/lib.rs

@@ -21,11 +21,12 @@ pub use crate::impl_::ExportedFunctions;
 // =================================================================================================
 
 // We use a (small) number of different tables here so there's more breaks and places to expand.
-pub static FUNCTIONS_CIRCUIT: ExportedFunctions = ExportedFunctions::empty()
-    .add_child(0, &circuit::FUNCTIONS)
-    .add_child(100, &dag::FUNCTIONS)
-    .add_child(200, &param::FUNCTIONS)
-    .add_child(250, &circuit_library::FUNCTIONS);
+pub static FUNCTIONS_CIRCUIT: ExportedFunctions =
+    ExportedFunctions::leaves(5, || vec![impl_::export_fn!(qiskit_cext::qk_api_version)])
+        .add_child(5, &circuit::FUNCTIONS)
+        .add_child(105, &dag::FUNCTIONS)
+        .add_child(205, &param::FUNCTIONS)
+        .add_child(255, &circuit_library::FUNCTIONS);
 pub static FUNCTIONS_QI: ExportedFunctions =
     ExportedFunctions::empty().add_child(0, &sparse_observable::FUNCTIONS);
 pub use transpiler::FUNCTIONS as FUNCTIONS_TRANSPILE;

crates/cext/src/lib.rs

@@ -24,3 +24,50 @@ pub mod sparse_observable;
 pub mod transpiler;
 
 pub use exit_codes::ExitCode;
+
+/// Get the C API version of the loaded library.
+///
+/// If you are dynamically linking against Qiskit, in either a stand-alone or Python-extension
+/// build, this function can be useful to check the version of the library actually loaded at
+/// runtime.  The header-file macro `QISKIT_VERSION_HEX` is the equivalent of this function, but
+/// for the version of the headers used at build time.
+///
+/// @return The version of the compiled Qiskit C API library, in the same format as the
+///     `QISKIT_VERSION_HEX` header-file macro.
+#[unsafe(no_mangle)]
+pub extern "C" fn qk_api_version() -> u32 {
+    const VERSION: u32 = {
+        const fn parse_int(s: &[u8]) -> u32 {
+            let mut i = 0;
+            let mut out = 0;
+            while i < s.len() {
+                if s[i] < b'0' || s[i] > b'9' {
+                    panic!("not a positive integer");
+                }
+                out *= 10;
+                out += (s[i] - b'0') as u32;
+                i += 1;
+            }
+            out
+        }
+
+        let mut v = (parse_int(env!("CARGO_PKG_VERSION_MAJOR").as_bytes()) << 24)
+            | (parse_int(env!("CARGO_PKG_VERSION_MINOR").as_bytes()) << 16)
+            | (parse_int(env!("CARGO_PKG_VERSION_PATCH").as_bytes()) << 8);
+        let pre = env!("CARGO_PKG_VERSION_PRE");
+        let pre = pre.as_bytes();
+        if let Some((b"dev", serial)) = pre.split_at_checked(3) {
+            v |= 0xa0 | parse_int(serial);
+        } else if let Some((b"beta", serial)) = pre.split_at_checked(4) {
+            v |= 0xb0 | parse_int(serial);
+        } else if let Some((b"rc", serial)) = pre.split_at_checked(2) {
+            v |= 0xc0 | parse_int(serial);
+        } else if pre.is_empty() {
+            v |= 0xf0;
+        } else {
+            panic!("could not parse 'CARGO_PKG_VERSION_PRE'");
+        }
+        v
+    };
+    VERSION
+}

crates/pyext/src/capi.rs

@@ -77,6 +77,7 @@ static FFI_QI: LazyLock<VTable> =
 pub fn capi_mod(m: &Bound<'_, PyModule>) -> PyResult<()> {
     static MODNAME: &str = "qiskit._accelerate.capi";
 
+    m.add("API_VERSION", qiskit_cext::qk_api_version())?;
     FFI_TRANSPILE.attach_pycapsule(m, MODNAME)?;
     FFI_CIRCUIT.attach_pycapsule(m, MODNAME)?;
     FFI_QI.attach_pycapsule(m, MODNAME)?;

docs/cdoc/version.rst

@@ -6,13 +6,17 @@ Qiskit's version can be queried using a set of compiler macros.
 
 .. c:macro:: QISKIT_VERSION
 
-    A human-readable version as ``char*``. For example: ``"2.1.0rc1"``.
+    A human-readable version as ``char*``. For example: ``"2.1.0-rc1"``.
 
 .. c:macro:: QISKIT_VERSION_HEX
 
-    The version number as 4-byte hexadecimal. The format is ``0xMMmmppls``, where 
+    The version number as 4-byte hexadecimal. The format is ``0xMMmmppls``, where
     ``M`` is the major, ``m`` is the minor, ``p`` is the patch, ``l`` is the release level
-    and ``s`` is the serial. For example, 2.1.0rc1 is ``0x020100C1``.
+    and ``s`` is the serial. For example, 2.1.0-rc1 is ``0x020100C1``.
+
+    Note that final versions, such as ``2.1.0``, will always end with ``0xF0`` in the last byte.
+
+    See :c:func:`qk_api_version` for the runtime version of this.
 
 .. c:macro:: QISKIT_VERSION_MAJOR
 
@@ -28,22 +32,28 @@ Qiskit's version can be queried using a set of compiler macros.
 
 .. c:macro:: QISKIT_RELEASE_LEVEL
 
-    The release level: ``0xA`` for the unreleased dev (or alpha) version, ``0xC`` for the 
-    release candidate, and ``0xF`` for the stable (or final) version.
+    The release level:
+
+    * ``0xA`` for an unreleased dev (or alpha) version
+    * ``0xB`` for a beta version
+    * ``0xC`` for a release candidate
+    * ``0xF`` for a stable (or final) version.
 
 .. c:macro:: QISKIT_RELEASE_SERIAL
 
-    This can be used to indicate the pre-release number in a pre-release series. 
-    For example, this would be set to ``1`` for ``2.1.0rc1``. This is ``0`` for the final version.
+    This can be used to indicate the pre-release number in a pre-release series.
+    For example, this would be set to ``4`` for ``2.1.0-rc4``. This is ``0`` for the final version.
 
 .. c:macro:: QISKIT_GET_VERSION_HEX(major, minor, patch, level, serial)
 
-    A macro to pack the version numbers into hexadecimal format. This can be used as 
-    tool to compare numbers, for example to ensure the current version is at least the 
+    A macro to pack the version numbers into hexadecimal format. This can be used as
+    tool to compare numbers, for example to ensure the current version is at least the
     stable 2.1.0 release do:
 
     .. code-block:: c
 
         if (QISKIT_VERSION_HEX >= QISKIT_GET_VERSION_HEX(2, 1, 0, 0xF, 0)) {
             // Code for version 2.1.0 (final) or later
         }
+
+.. doxygenfunction:: qk_api_version

releasenotes/notes/c-api-version-6b3a43c4b9c260b4.yaml

@@ -0,0 +1,4 @@
+---
+features_c:
+  - The C API now provides :c:func:`qk_api_version`, which returns the version of the library that
+    has been loaded at runtime.  The return format is the same as :c:macro:`QISKIT_VERSION_HEX`.

test/c/test_version_info.c

@@ -77,10 +77,23 @@ static int test_version_macros(void) {
     return Ok;
 }
 
+/**
+ * Test the version in the header matches the version returned from the library.
+ */
+static int test_header_vs_lib(void) {
+    if (qk_api_version() != QISKIT_VERSION_HEX) {
+        fprintf(stderr, "%s: QISKIT_VERSION_HEX (%x) does not match qk_api_version() (%x)\n",
+                __func__, QISKIT_VERSION_HEX, qk_api_version());
+        return EqualityError;
+    }
+    return Ok;
+}
+
 int test_version_info(void) {
     int num_failed = 0;
     num_failed += RUN_TEST(test_version);
     num_failed += RUN_TEST(test_version_macros);
+    num_failed += RUN_TEST(test_header_vs_lib);
 
     fprintf(stderr, "=== Number of failed subtests: %i\n", num_failed);
     fflush(stderr);