Skip to content

Add an ABI-v1 C interface - #47

Merged
Konstantin V Shvachko (shvachko) merged 3 commits into
microsoft:mainfrom
xufyan:checked-c-abi-v1
Nov 18, 2026
Merged

Konstantin V Shvachko (shvachko) merged 3 commits into
microsoft:mainfrom
xufyan:checked-c-abi-v1

Conversation

@xufyan

@xufyan xufyan commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add an unpublished, caller-buffered bf-tree-ffi package.
Use the existing native read, scan, insert, delete, and CPR operations.

The only native additions are two read-only Config getters:
get_cb_min_record_size and get_max_key_len.
They preserve recovery-limit validation without changing engine operations.

The package preserves ABI-v1 layouts, signatures, statuses, and caller-owned buffers.
It adds versioned capability discovery and bounded scans.
It includes Rust/C/C++ conformance tests, CMake build/install support, source-package filtering, and Windows/Linux CI.

Scope

tree.rs, leaf operations, mini-page operations, range scans, and snapshot code match the upstream base exactly.
The native result types, algorithms, and persisted formats remain unchanged.
Native checked-operation APIs and their dedicated tests are outside this contribution.

Interface contracts

  • Existing-tree open remains explicitly unsupported. Recovery uses a native CPR snapshot.
  • Reads and scans use scratch space sized from the effective tree configuration, including recovered limits.
  • The C interface catches Rust unwinding and fences affected handles. It cannot recover process aborts or native undefined behavior.
  • BUFFER_TOO_SMALL leaves caller byte/descriptor buffers unchanged. Scans return complete records within their selected limits.
  • Native scan constructors retain inclusive endpoints. The additional C bounded-scan operation uses an exclusive upper bound.
  • Recovery requires an exclusively owned, validated native artifact. Use a private copy when the published snapshot must remain immutable.
  • Delete serializes its existence check and mutation. Snapshot capture serializes requests per handle.
  • Native WAL is disabled by the package. Atomic multi-record batches, native I/O metrics, and power-loss durability are not advertised.

See bf-tree-ffi/README.md for the detailed contract.

Local validation

Environment: Windows x64, Rust 1.93.0, MSVC 19.51.

  • The configuration-getter unit test.
  • Thirteen Rust C-interface tests, including a real legacy-read panic and recovery with nondefault limits.
  • Package Clippy with -D warnings.
  • C and C++ Release consumers through CMake/CTest.
  • A C++ consumer compiled against the unchanged downstream ABI-v1 header.
  • Exported C symbols, source-package inventory, and installed header/library/license bundle.

The existing native spdk configuration and dead-code warnings remain unchanged.

Release boundaries

This is a review candidate, not a published package or an application migration.
publish = false is intentional.
The adjacent native source includes two configuration getters that its 0.5.7 version number alone does not identify.
Publication requires approved, compatible native and FFI versions or another immutable source mechanism.

Windows ARM64 runtime, controlled performance, and broader durability qualification remain open.
The added CI job covers Windows x64 and Linux x64; it does not replace Windows ARM64 qualification.
Application adoption also requires snapshot compatibility and rollback from newly produced data.

An earlier unseeded Windows native-suite run stalled in
stateful_operations_match_ordered_model::case_2_std_io.
Seeded comparisons did not reproduce it.
Its cause remains unproven, and this revision does not claim a fix.

@xufyan xufyan changed the title Add checked Rust APIs and an ABI-v1 C interface Add an ABI-v1 C interface Nov 5, 2026
@shvachko

Copy link
Copy Markdown
Contributor

Thanks xufyan for the PR. This looks good to me.

One request for FetchContent consumption: please add an option such as BF_TREE_FFI_BUILD_TESTS to guard the C/C++ test targets, enable_testing(), and add_test() calls.

This would let downstream projects to disable dependency tests without disabling its own tests. Standalone builds and upstream CI can keep the FFI tests enabled.

EXCLUDE_FROM_ALL alone is insufficient: it excludes the test executables from the default build but leaves BfTreeCAbi and BfTreeCppAbi registered with CTest.

@xufyan

xufyan commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Konstantin V Shvachko (@shvachko) Added BF_TREE_FFI_BUILD_TESTS in 9e24110. It defaults to ON, so standalone builds and existing CI keep both ABI tests enabled.

With -DBF_TREE_FFI_BUILD_TESTS=OFF, the dependency creates neither C/C++ test target, does not call enable_testing(), and registers neither CTest test. The README documents the option for FetchContent consumers.

Checked Windows x64 Release: both default ABI tests pass. A fresh standalone OFF configuration registers zero tests. A FetchContent parent with the option OFF builds and passes its own C++ consumer test, with neither dependency test target or registration present.

@shvachko
Konstantin V Shvachko (shvachko) merged commit aa298d9 into microsoft:main Nov 18, 2026
6 checks passed
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.

2 participants