From a3fca4789fa1096e0915a2847769d734fd52058d Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Sat, 27 Jun 2026 19:58:24 +0200 Subject: [PATCH] docs: record experimental-tier exclusion (CCtxParams) in binding scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ZSTD_CCtx_params bundle is ZSTDLIB_STATIC_API — experimental tier. The symbols are exported (the macro resolves to visibility("default"), so the FFM layer could bind them by name), but they carry no API-stability guarantee and may change or be removed between zstd releases. The bundle only saves a few setParameter calls at context init, and the stable per-context ZSTD_CCtx_setParameter path (already bound) covers the same need, so it is intentionally not bound. Extend ADR 0013 to exclude the experimental tier and note the reason on the supported.md Advanced parameters row. Co-Authored-By: Claude Opus 4.8 --- adr/0013-binding-coverage-scope.md | 15 +++++++++++++-- docs/supported.md | 2 +- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/adr/0013-binding-coverage-scope.md b/adr/0013-binding-coverage-scope.md index ba326ca..0a616af 100644 --- a/adr/0013-binding-coverage-scope.md +++ b/adr/0013-binding-coverage-scope.md @@ -1,4 +1,4 @@ -# ADR 0013: Binding coverage scope — exclude legacy/deprecated +# ADR 0013: Binding coverage scope — exclude legacy/deprecated/experimental - **Status:** Accepted - **Date:** 2026-06-27 @@ -18,6 +18,16 @@ training), and frame/skippable-frame introspection. **Exclude** deprecated functions and the `legacy/` and `deprecated/` source trees (the native build compiles only `common`, `compress`, `decompress`, `dictBuilder`). +Also **exclude the experimental tier** — symbols declared `ZSTDLIB_STATIC_API`. +These are exported by the build (the macro resolves to `visibility("default")`, +so the FFM layer could bind them by name), but they carry no API-stability +guarantee and may change or be removed between zstd releases. Notably this +covers the `ZSTD_CCtx_params` bundle (`ZSTD_createCCtxParams`, +`ZSTD_CCtxParams_setParameter`, `ZSTD_CCtx_setParametersUsingCCtxParams`, …): +it only saves a few `setParameter` calls at context init — never on a hot path — +so the experimental-API risk is not worth the marginal value. The stable, +already-bound per-context `ZSTD_CCtx_setParameter` path covers the same need. + The full coverage map — every public symbol, what is bound, and what is intentionally omitted — is maintained in `docs/supported.md`. @@ -46,5 +56,6 @@ intentionally omitted — is maintained in `docs/supported.md`. ## References -- [docs/supported.md](../docs/supported.md), [Bindings.java] +- [docs/supported.md](../docs/supported.md), + [Bindings.java](../zstd/src/main/java/io/github/dfa1/zstd/Bindings.java) - [scripts/build-zstd.sh](../scripts/build-zstd.sh) diff --git a/docs/supported.md b/docs/supported.md index 92753fc..97e5f71 100644 --- a/docs/supported.md +++ b/docs/supported.md @@ -33,7 +33,7 @@ rather than the deprecated `ZSTD_getDecompressedSize`. | Dictionary training (ZDICT) | 8 / 12 | trainFromBuffer, cover/fastCover optimizers, finalizeDictionary, getDictHeaderSize | | Streaming — compress | 3 / 22 | `ZstdOutputStream` (compressStream2 + buffer sizes) | | Streaming — decompress | 3 / 15 | `ZstdInputStream` (decompressStream + buffer sizes) | -| Advanced parameters | 14 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `C/DCtx_reset`, `C/DCtx_loadDictionary`, `CCtx_refCDict`/`DCtx_refDDict`, `C/DCtx_refPrefix`, `c/dParam_getBounds`; MT inert on single-thread build | +| Advanced parameters | 14 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `C/DCtx_reset`, `C/DCtx_loadDictionary`, `CCtx_refCDict`/`DCtx_refDDict`, `C/DCtx_refPrefix`, `c/dParam_getBounds`; MT inert on single-thread build. The `ZSTD_CCtx_params` bundle (the 10 unbound rows in this section's table below) is experimental (`ZSTDLIB_STATIC_API`, no stability guarantee — exported, but intentionally not surfaced) — see [ADR 0013](../adr/0013-binding-coverage-scope.md) | | Frame inspection | 12 / 13 | `ZstdFrame` + getFrameProgression; `_advanced` not bound | | Memory sizing | 9 / 14 | sizeof_C/DCtx, sizeof_C/DDict, estimate C/DCtx + C/DDict size, in-place decompression margin | | Low-level block | 0 / 12 | expert block/continue API not bound |