Repository navigation
Add a C ABI for the sampler API - #119
Open
joshbainbridge wants to merge 10 commits into
Open
joshbainbridge wants to merge 10 commits into
joshbainbridge wants to merge 10 commits into
Conversation
joshbainbridge
force-pushed
the
c-abi
branch
from
November 16, 2026 16:04
487feb5 to
7d3c982
Compare
The documentation for the sampler interface contains a number of spelling and grammar mistakes. These were found while adapting the same documentation for the C ABI header. Correct the spelling of available, noticeable, implementation, indices, globally, multiplier, multipliers and exchange. Add missing words in two sentences, fix the tense of preserve, and add a missing full stop. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
GitHub retired the macOS 14 runner image on November 2, 2026, so any job using the macos-14 label is now cancelled before it starts, with no runner assigned. Replace the macos-14 label with macos-15 across the CI pipeline, pinning a version in line with the Ubuntu and Windows runners. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
Linking the planned C ABI library from C leaves operator new[] and operator delete[] unresolved, pulling in the C++ runtime. The only source is the scratch buffer in stochasticPmjInit, reached through PMJ cache initialisation. Allocate the buffer with std::malloc and release it with std::free. The buffer needs no construction, and an assertion covers allocation failure in line with the precondition style used across the library. Record the change in the changelog. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
joshbainbridge
force-pushed
the
c-abi
branch
2 times, most recently
from
November 16, 2026 18:12
4908e3d to
2816328
Compare
OpenQMC can only be used directly from C++. A C ABI lets any language with C FFI support use the samplers, such as C, Zig and Rust, to encourage broader adoption. Add oqmc_c.h, a C11 header declaring an opaque 16 byte sampler value and functions wrapping the sampler interface. Defining OQMC_IMPLEMENTATION in one C++17 translation unit also emits the implementation, wrapping the sampler chosen by an OQMC_CABI_SAMPLER_* definition and defaulting to pmjbn. Add src/oqmc_impl.cpp as that translation unit for the library build. Drop the OQMC_API linkage macro from the spec, leaving symbol visibility to the linking binary, such as a plugin using a version script. Mark the functions for export when OQMC_CABI_EXPORT_SYMBOLS is defined, so that a shared library can hide all other symbols, including the C++ implementation and its tables. Statically assert that the sampler fits the size and alignment of the opaque value. Trivial copyability is by design and not asserted, as that needs <type_traits> or a compiler builtin, so update both spec options to match. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
The C ABI header needs a compiled library that downstream projects can link from C, and that OpenQMC can install and distribute. Add the OPENQMC_BUILD_CABI option, with OPENQMC_CABI_SHARED_LIB and OPENQMC_CABI_FORCE_PIC following the options of the removed binary variant, and OPENQMC_CABI_SAMPLER to select the wrapped sampler. Build src/oqmc_impl.cpp into liboqmc, exported as OpenQMC::CABI without propagating the C++ standard. Build both libraries with hidden visibility, so plugins linking the static library keep the symbols private, and the shared library exports only the C ABI functions, which the header marks for export in a shared build. Enable the option in the presets, and update the spec to the new option names. Link with -nodefaultlibs and add back only the C library, so the library doesn't depend on the C++ runtime. Unlike -nostdlib++, which needs GCC 13 or later, this works with the GCC versions of the supported VFX Reference Platforms. Skip this on Windows, which has no library named c, and where MSVC doesn't recognise the flag. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
The C ABI must produce the same values as the C++ sampler interface. The C++ samplers are also documented as small and trivially copyable, which the C ABI relies on, but this was never checked. Add a GoogleTest file comparing every C function bit for bit against the equivalent C++ call for the selected sampler, including domain trees, copies and self assignment. Also include a layout test to each sampler checking it is trivially copyable, with its expected size and alignment. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
The C ABI library wraps a single sampler chosen when it is built, and the unit tests only cover the default. A change that broke the C ABI for one of the other samplers would pass CI unnoticed. Add a test-cabi job that builds the tests once for each sampler and runs the C ABI tests against it. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
C consumers of the shared C ABI library should need nothing beyond the C standard library (libc). Any other dependency, such as the C++ runtime, would be passed on to every program linking the library. Add check-cabi-deps.sh to list the dynamic dependencies of the shared library on Linux and macOS, failing on anything beyond libc. Run it on CI against a shared build on Linux, ahead of the install job. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
Downstream use is validated on CI through the examples, but none link the C ABI library. Nothing checks that the header is valid C, or that a C only project can link the installed library with a C toolchain alone, so a missing symbol, or one from beyond the C library, would go unnoticed. Add a C example that finds the installed package, links OpenQMC::CABI, and calls every function in the C ABI, checking the value layout and the range of drawn values. Add a check-symbols job that installs the library, then builds and runs the example with strict C11 warnings, for every sampler as a static library and one shared build per platform, ahead of the install job. Extend the format and lint scripts to C files, ignore local install directories, and update the spec. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
The C ABI header and library are not yet described in the docs, so downstream users have no guidance on building, linking or selecting the sampler. Add a section to the readme on using the library from C, covering the CMake target, sampler selection, self compilation and plugins, and document the new build options. Describe the dependency check and how to run the C example in the contributing guide. Mention the C ABI in the feature list and docs home page, and record the changes in the changelog. Signed-off-by: Josh Bainbridge <josh.bainbridge@gmail.com>
joshbainbridge
force-pushed
the
c-abi
branch
from
November 16, 2026 19:01
2816328 to
c0fe70e
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #87. Implements Option A of the C ABI specification added in #95 (
specs/c-abi/spec.md,specs/c-abi/optiona.md).OpenQMC can only be used directly from C++. This adds a stable C ABI so that any language with C FFI support (C, Zig, Rust, and so on) can use the samplers. The C++ header-only library is unchanged.
Overview
include/oqmc/oqmc_c.his a C11 header declaring an opaque 16 byteoqmc_samplervalue and 12oqmc_sampler_*functions wrappingSamplerInterface: cache, create, the four domain derivations, and the draw functions for samples and pseudo random values.OQMC_IMPLEMENTATIONin one C++17 translation unit also emits the implementation, wrapping a single sampler chosen at compile time byOQMC_CABI_SAMPLER_*(default PMJBN).src/oqmc_impl.cppdoes this for the library build.OPENQMC_BUILD_CABICMake option buildsliboqmc, exported asOpenQMC::CABI. It doesn't propagate the C++ standard, so C-only projects can consume it.Commits
Each commit is self-contained and can be reviewed in order.
sampler.h, found while adapting its documentation for the C header.macos-14runner image was retired, so jobs using it no longer start. Unrelated to the C ABI.new[]/delete[]instochasticPmjInit, the last use of the C++ runtime in the headers.oqmc_c.handsrc/oqmc_impl.cpp, with static assertions on the value's size and alignment. Updates the spec to drop theOQMC_APIlinkage macro.OpenQMC::CABItarget, and the option enabled in the presets. Links with-nodefaultlibsplus libc (except on Windows), with hidden visibility for both, and the shared library exporting only the C ABI functions (OQMC_CABI_EXPORT_SYMBOLS).test-cabijob with a matrix over the six samplers.scripts/check-cabi-deps.sh, and acheck-dynamic-dependenciesjob for the shared library on Linux.cmake/examples/cabicalling every function, and acheck-symbolsjob that installs the library and builds the example as strict C11, for every sampler as a static library and one shared build per platform. Format and lint scripts extended to C files.Build options
OPENQMC_BUILD_CABION,OFFOFF(ONin the presets)OPENQMC_CABI_SAMPLERPMJ,PMJBN,SOBOL,SOBOLBN,LATTICE,LATTICEBNPMJBNOPENQMC_CABI_SHARED_LIBON,OFFOFFOPENQMC_CABI_FORCE_PICON,OFFOFFThe library structure follows the binary variant removed in 5b6d8aa.
OPENQMC_CABI_SHARED_LIBandOPENQMC_CABI_FORCE_PICreplace the oldOPENQMC_SHARED_LIBandOPENQMC_FORCE_PIC, scoped to the C ABI library.Dependencies and symbols
The shared library depends only on the C standard library (
libc.so.6on Linux, as checked by CI), and exports only the 12 C ABI functions. The C++ implementation and its tables are hidden. On macOS (Debug build):On static library builds, these are all hidden to avoid shared plugins in larger applications conflicting with different versions of OpenQMC.
Testing
just testtest-cabi)check-symbols)check-format.sh,check-lint.sh,check-documentation.shNotes for reviewers
check-symbols. Dependencies beyond libc are caught bycheck-dynamic-dependencies.-nodefaultlibsis skipped there. MSVC already rejects unresolved symbols and only links its C++ library when the standard library is used, so no Windows dependency check was added.OPENQMC_CABI_SAMPLER, following the spec, rather than the all-samplerOPENQMC_ENABLE_C_ABIdesign described in Add C-ABI to provide an ABI stable interface and improve compatibility #87.@fpsunflower and @hills you both have already given a lot of feedback here and shaped the implementation, but I'll leave this open to comment for a short period incase you are interested :)