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 |