Skip to content

Add a C ABI for the sampler API - #119

Open
joshbainbridge wants to merge 10 commits into
mainfrom
c-abi
Open

joshbainbridge wants to merge 10 commits into
mainfrom
c-abi

Conversation

@joshbainbridge

@joshbainbridge joshbainbridge commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

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.h is a C11 header declaring an opaque 16 byte oqmc_sampler value and 12 oqmc_sampler_* functions wrapping SamplerInterface: cache, create, the four domain derivations, and the draw functions for samples and pseudo random values.
  • Defining OQMC_IMPLEMENTATION in one C++17 translation unit also emits the implementation, wrapping a single sampler chosen at compile time by OQMC_CABI_SAMPLER_* (default PMJBN). src/oqmc_impl.cpp does this for the library build.
  • The new OPENQMC_BUILD_CABI CMake option builds liboqmc, exported as OpenQMC::CABI. It doesn't propagate the C++ standard, so C-only projects can consume it.
  • The shared library depends on nothing beyond the C standard library (libc). The static library is built with hidden visibility, so plugins linking it keep the symbols private.
#include <oqmc/oqmc_c.h>

void* cache = malloc(oqmc_sampler_cache_size());
oqmc_sampler_initialise_cache(cache);

const oqmc_sampler pixel = oqmc_sampler_create(x, y, 0, index, cache);
const oqmc_sampler domain = oqmc_sampler_new_domain(&pixel, 0);

float sample[2];
oqmc_sampler_draw_sample_f(&domain, 2, sample);

free(cache);

Commits

Each commit is self-contained and can be reviewed in order.

Commit Description
Fix typos in the sampler interface documentation Typos in sampler.h, found while adapting its documentation for the C header.
Update macOS CI runners to macOS 15 The macos-14 runner image was retired, so jobs using it no longer start. Unrelated to the C ABI.
Allocate PMJ scratch buffer with malloc Replaces new[]/delete[] in stochasticPmjInit, the last use of the C++ runtime in the headers.
Add C ABI header for the sampler API oqmc_c.h and src/oqmc_impl.cpp, with static assertions on the value's size and alignment. Updates the spec to drop the OQMC_API linkage macro.
Add CMake build for the C ABI library Build options, the OpenQMC::CABI target, and the option enabled in the presets. Links with -nodefaultlibs plus libc (except on Windows), with hidden visibility for both, and the shared library exporting only the C ABI functions (OQMC_CABI_EXPORT_SYMBOLS).
Add tests for the C ABI library GoogleTest comparison against the C++ API, and a layout test for each sampler.
Run the C ABI tests for every sampler on CI New test-cabi job with a matrix over the six samplers.
Check the C ABI library depends only on the C library scripts/check-cabi-deps.sh, and a check-dynamic-dependencies job for the shared library on Linux.
Add a downstream C example for the C ABI library cmake/examples/cabi calling every function, and a check-symbols job 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.
Document the C ABI library README, CONTRIBUTING, CHANGELOG and docs home page.

Build options

Option Values Default
OPENQMC_BUILD_CABI ON, OFF OFF (ON in the presets)
OPENQMC_CABI_SAMPLER PMJ, PMJBN, SOBOL, SOBOLBN, LATTICE, LATTICEBN PMJBN
OPENQMC_CABI_SHARED_LIB ON, OFF OFF
OPENQMC_CABI_FORCE_PIC ON, OFF OFF

The library structure follows the binary variant removed in 5b6d8aa. OPENQMC_CABI_SHARED_LIB and OPENQMC_CABI_FORCE_PIC replace the old OPENQMC_SHARED_LIB and OPENQMC_FORCE_PIC, scoped to the C ABI library.

Dependencies and symbols

The shared library depends only on the C standard library (libc.so.6 on 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):

% du -h build/src/liboqmc.dylib
600K    build/src/liboqmc.dylib
% nm -gu build/src/liboqmc.dylib
___assert_rtn
___stack_chk_fail
___stack_chk_guard
_free
_malloc
_memcpy
dyld_stub_binder
% nm -gU build/src/liboqmc.dylib | c++filt
00000000000044b0 T _oqmc_sampler_cache_size
0000000000004514 T _oqmc_sampler_create
0000000000005290 T _oqmc_sampler_draw_rnd_f
00000000000050e4 T _oqmc_sampler_draw_rnd_u
0000000000004f38 T _oqmc_sampler_draw_sample_f
0000000000004d8c T _oqmc_sampler_draw_sample_u
00000000000044c4 T _oqmc_sampler_initialise_cache
0000000000004498 T _oqmc_sampler_name
00000000000046b8 T _oqmc_sampler_new_domain
0000000000004be4 T _oqmc_sampler_new_domain_chain
0000000000004a50 T _oqmc_sampler_new_domain_distrib
0000000000004874 T _oqmc_sampler_new_domain_split
% ./scripts/check-cabi-deps.sh build/src/liboqmc.dylib && echo PASS
Dependencies of build/src/liboqmc.dylib:
/usr/lib/libSystem.B.dylib
PASS

On static library builds, these are all hidden to avoid shared plugins in larger applications conflicting with different versions of OpenQMC.

Testing

Check Result
Full test suite, just test 186 tests pass, including 11 C ABI tests (10 comparison tests and a layout test)
C ABI tests per sampler (test-cabi) All six samplers pass on CI
C example linked from C (check-symbols) All six samplers as static libraries, and a shared build, pass on Linux and macOS
Dependency check, shared library Passes on CI (Linux) and locally on macOS
check-format.sh, check-lint.sh, check-documentation.sh Pass
Docs site build Builds with no new warnings

Notes for reviewers

  • Missing symbols, including any use of the C++ runtime, are caught by linking the C example, a pure C project, against the installed library in check-symbols. Dependencies beyond libc are caught by check-dynamic-dependencies.
  • Windows: the static library builds through the existing Windows preset, and -nodefaultlibs is 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.
  • The C ABI wraps one sampler chosen at build time with OPENQMC_CABI_SAMPLER, following the spec, rather than the all-sampler OPENQMC_ENABLE_C_ABI design described in Add C-ABI to provide an ABI stable interface and improve compatibility #87.
  • Option B from the spec (runtime sampler selection) isn't part of this change. The API and value layout keep it possible as a future addition.

@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 :)

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
joshbainbridge force-pushed the c-abi branch 2 times, most recently from 4908e3d to 2816328 Compare November 16, 2026 18:12
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>

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add C-ABI to provide an ABI stable interface and improve compatibility

1 participant