add PVXS_ABI_VERSION

documentation/util.rst

@@ -76,6 +76,8 @@ Compile time access to PVXS library version information. ::
 
 .. doxygendefine:: PVXS_VERSION
 
+.. doxygendefine:: PVXS_ABI_VERSION
+
 .. doxygendefine:: VERSION_INT
 
 eg. to conditionally compile based on library version. ::
@@ -88,6 +90,10 @@ eg. to conditionally compile based on library version. ::
 
 .. doxygenfunction:: pvxs::version_str
 
+.. doxygenfunction:: pvxs::version_abi_int
+
+.. doxygenfunction:: pvxs::version_abi_check
+
 Unit-test helpers
 -----------------
 

src/pvxs/version.h

@@ -45,6 +45,10 @@
 //! Current library version
 #define PVXS_VERSION VERSION_INT(PVXS_MAJOR_VERSION, PVXS_MINOR_VERSION, PVXS_MAINTENANCE_VERSION, 0)
 
+//! Current library ABI version
+//! @since UNRELEASED
+#define PVXS_ABI_VERSION VERSION_INT(PVXS_MAJOR_VERSION, PVXS_MINOR_VERSION, 0, 0)
+
 #ifdef __GNUC__
 #  define GCC_VERSION VERSION_INT(__GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__, 0)
 #endif
@@ -59,6 +63,28 @@ const char *version_str();
 PVXS_API
 unsigned long version_int();
 
+//! @returns PVXS_ABI_VERSION captured at library compile time
+//! @since UNRELEASED
+PVXS_API
+unsigned long version_abi_int();
+
+/** Runtime ABI check.
+ *
+ * This test is only meaningful if it is preformed prior to any
+ * other library calls.
+ *
+ * It is guaranteed that the library has no global constructors.
+ *
+ * @returns true if the header and library ABI versions match,
+ *               and if the header version is not newer than the library version.
+ *
+ * @since UNRELEASED
+ */
+static inline
+bool version_abi_check() {
+    return PVXS_ABI_VERSION==version_abi_int() && PVXS_VERSION<=version_int();
+}
+
 }
 
 #endif // PVXS_VERSION_H

src/util.cpp

@@ -47,6 +47,11 @@ unsigned long version_int()
     return PVXS_VERSION;
 }
 
+unsigned long version_abi_int()
+{
+    return PVXS_ABI_VERSION;
+}
+
 
 #define CASE(KLASS) std::atomic<size_t> cnt_ ## KLASS{}