feat: add ZSTD_CCtx_reset / ZSTD_DCtx_reset context recycling

Bind ZSTD_CCtx_reset and ZSTD_DCtx_reset behind a new ZstdResetDirective
enum (SESSION_ONLY, PARAMETERS, SESSION_AND_PARAMETERS), exposed as
ZstdCompressCtx.reset(...) / ZstdDecompressCtx.reset(...). Lets a pooled
or long-lived context recycle its native state between frames without
freeing and recreating it.

A parameter reset clears the context back to defaults, so the compress
context drops its cached level back to Zstd.defaultCompressionLevel() to
stay in sync with the native state.

Document the recipe in docs/how-to.md, flip both symbols to bound in
docs/supported.md (advanced-parameter count 8 -> 10, total 55 -> 57), and
add the 0.5 changelog entry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions are released as `v*`
 git tags, which trigger publication to Maven Central.
 
+## [0.5]
+
+### Added
+- `ZstdCompressCtx.reset(ZstdResetDirective)` / `ZstdDecompressCtx.reset(...)` —
+  recycle a context's native state between frames without freeing and recreating
+  it. `SESSION_ONLY` keeps the level, parameters, and dictionary; `PARAMETERS` /
+  `SESSION_AND_PARAMETERS` restore the defaults. Binds `ZSTD_CCtx_reset` /
+  `ZSTD_DCtx_reset`.
+
+### Changed
+- `NativeLibrary.classifier()` now throws a clear `UnsatisfiedLinkError` naming
+  the unsupported CPU arch instead of silently mapping it to x86_64 (which
+  deferred failure to a cryptic `dlopen` error). Added an explicit `amd64`
+  branch so Linux JVMs (which report `os.arch=amd64`) still resolve x86_64.
+  ([ea1ac84](https://github.com/dfa1/zstd-java/commit/ea1ac84))
+
+### Fixed
+- Native JARs are much smaller. The ELF shared library is now stripped at link
+  time (`-s`), dropping debug info (`libzstd.so` 4.0M -> ~650K), and the
+  multi-MB `.pdb` debug database and `.lib` import library that lld emits next
+  to the Windows `.dll` are no longer bundled (neither is needed at runtime).
+  Net: linux-x86_64 native jar 1.2M -> 285K, windows-x86_64 1.2M -> 372K.
+  ([ea1ac84](https://github.com/dfa1/zstd-java/commit/ea1ac84))
+
 ## [0.4]
 
 ### Added

docs/how-to.md

@@ -18,6 +18,31 @@ try (ZstdCompressCtx cctx = new ZstdCompressCtx().level(19);
 Pick the level explicitly with `Zstd.maxCompressionLevel()` /
 `minCompressionLevel()` when you need the extreme ends.
 
+## Reset a context to recycle it
+
+A context is already reusable across whole `compress` / `decompress` calls. Reset
+goes further: it recycles the *native state* of one context — for pooled contexts,
+or to abort a half-written frame and start clean — without freeing and recreating
+it. Pick what to clear with `ZstdResetDirective`:
+
+```java
+try (ZstdCompressCtx cctx = new ZstdCompressCtx().level(19)) {
+    byte[] a = cctx.compress(first);
+
+    // Cheap: drop any unflushed frame state, keep the level and parameters.
+    cctx.reset(ZstdResetDirective.SESSION_ONLY);
+    byte[] b = cctx.compress(second);
+
+    // Full wipe: parameters back to default, dictionary cleared, level reset to
+    // Zstd.defaultCompressionLevel(). Only valid between frames, not mid-frame.
+    cctx.reset(ZstdResetDirective.SESSION_AND_PARAMETERS);
+}
+```
+
+`ZstdDecompressCtx.reset(...)` works the same way. Reuse alone amortises
+allocation; reset lets a long-lived or pooled context return to a known state
+without churning native memory.
+
 ## Compress many small payloads with a dictionary
 
 For many small, similar payloads (log lines, JSON records, protobufs), a

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 | 8 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `loadDictionary`, `c/dParam_getBounds`; MT inert on single-thread build |
+| Advanced parameters | 10 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `C/DCtx_reset`, `loadDictionary`, `c/dParam_getBounds`; MT inert on single-thread build |
 | Frame inspection | 10 / 13 | `ZstdFrame` + getFrameProgression; `_advanced` not bound |
 | Memory sizing | 8 / 14 | sizeof_C/DCtx, sizeof_C/DDict, estimate C/DCtx + C/DDict size |
 | Low-level block | 0 / 12 | expert block/continue API not bound |
@@ -63,6 +63,7 @@ rather than the deprecated `ZSTD_getDecompressedSize`.
 | `ZSTD_compress2`, `ZSTD_CCtx_setParameter` | `ZstdCompressCtx.parameter` / `checksum` / `longDistanceMatching` / `windowLog` (all of `ZstdCompressParameter`) |
 | `ZSTD_DCtx_setParameter` | `ZstdDecompressCtx.parameter` / `windowLogMax` (`ZstdDecompressParameter`) |
 | `ZSTD_CCtx_setPledgedSrcSize` | `ZstdOutputStream.withPledgedSize` |
+| `ZSTD_CCtx_reset`, `ZSTD_DCtx_reset` | `ZstdCompressCtx.reset` / `ZstdDecompressCtx.reset` (`ZstdResetDirective`) |
 | `ZSTD_getDictID_fromCDict`, `ZSTD_getDictID_fromDDict` | `ZstdCompressDict.id()` / `ZstdDecompressDict.id()` |
 | `ZSTD_getErrorString` | `ZstdErrorCode.description()` |
 | `ZSTD_cParam_getBounds`, `ZSTD_dParam_getBounds` | `ZstdCompressParameter.bounds()` / `ZstdDecompressParameter.bounds()` (`ZstdBounds`) |
@@ -90,7 +91,7 @@ zstd-jni's JNI sources (v1.5.7-11, `src/main/native/*.c`). The latter is
 symbol-exact, not functional equivalence: zstd-jni may expose an operation through
 a different symbol than this library — e.g. it routes one-shot compression through
 `ZSTD_compress2`, so `ZSTD_compress` reads `—` for it even though `Zstd.compress`
-works. zstd-jni references 53 of these symbols; this library binds 55. They
+works. zstd-jni references 53 of these symbols; this library binds 57. They
 overlap on the modern context/streaming API and diverge mainly on zstd-jni's
 sequence-producer hooks vs this library's frame-inspection and typed-error surface.
 
@@ -231,7 +232,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_resetDStream` | — ᵈ | — |
 | `ZSTD_sizeof_DStream` | — | — |
 
-### Advanced parameters (8/38)
+### Advanced parameters (10/38)
 
 | Symbol | Bound | zstd-jni |
 |---|:---:|:---:|
@@ -249,7 +250,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_CCtx_refPrefix` | — | — |
 | `ZSTD_CCtx_refPrefix_advanced` | — | — |
 | `ZSTD_CCtx_refThreadPool` | — | — |
-| `ZSTD_CCtx_reset` | — | ✅ |
+| `ZSTD_CCtx_reset` | ✅ | ✅ |
 | `ZSTD_CCtx_setCParams` | — | — |
 | `ZSTD_CCtx_setFParams` | — | — |
 | `ZSTD_CCtx_setParameter` | ✅ | ✅ |
@@ -263,7 +264,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_DCtx_refDDict` | — | ✅ |
 | `ZSTD_DCtx_refPrefix` | — | — |
 | `ZSTD_DCtx_refPrefix_advanced` | — | — |
-| `ZSTD_DCtx_reset` | — | ✅ |
+| `ZSTD_DCtx_reset` | ✅ | ✅ |
 | `ZSTD_DCtx_setFormat` | — ᵈ | — |
 | `ZSTD_DCtx_setMaxWindowSize` | — | — |
 | `ZSTD_DCtx_setParameter` | ✅ | ✅ |

zstd/src/main/java/io/github/dfa1/zstd/Bindings.java

@@ -138,6 +138,11 @@ final class Bindings {
             NativeLibrary.lookup("ZSTD_CCtx_setParameter",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_INT, JAVA_INT));
 
+    // size_t ZSTD_CCtx_reset(ZSTD_CCtx*, ZSTD_ResetDirective)
+    static final MethodHandle CCTX_RESET =
+            NativeLibrary.lookup("ZSTD_CCtx_reset",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_INT));
+
     // size_t ZSTD_compress2(ZSTD_CCtx*, void* dst, size_t dstCap, const void* src, size_t srcSize)
     // Uses the advanced parameters set on the context (unlike ZSTD_compressCCtx).
     static final MethodHandle COMPRESS2 =
@@ -149,6 +154,11 @@ final class Bindings {
             NativeLibrary.lookup("ZSTD_DCtx_setParameter",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_INT, JAVA_INT));
 
+    // size_t ZSTD_DCtx_reset(ZSTD_DCtx*, ZSTD_ResetDirective)
+    static final MethodHandle DCTX_RESET =
+            NativeLibrary.lookup("ZSTD_DCtx_reset",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_INT));
+
     // size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx*, unsigned long long pledgedSrcSize)
     static final MethodHandle CCTX_SET_PLEDGED_SRC_SIZE =
             NativeLibrary.lookup("ZSTD_CCtx_setPledgedSrcSize",

zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressCtx.java

@@ -90,6 +90,28 @@ public ZstdCompressCtx windowLog(int windowLog) {
         return parameter(ZstdCompressParameter.WINDOW_LOG, windowLog);
     }
 
+    /// Resets this context so it can be reused for the next frame without the
+    /// cost of freeing and recreating its native state.
+    ///
+    /// - [ZstdResetDirective#SESSION_ONLY] aborts the current frame and drops
+    ///   unflushed data, keeping the level, parameters, and any dictionary.
+    /// - [ZstdResetDirective#PARAMETERS] and
+    ///   [ZstdResetDirective#SESSION_AND_PARAMETERS] also restore every
+    ///   parameter to its default and clear the dictionary; the level returns to
+    ///   [Zstd#defaultCompressionLevel()]. Only valid when no frame is in progress.
+    ///
+    /// @param directive what to clear
+    /// @return `this`, for chaining
+    /// @throws ZstdException if a parameter reset is requested mid-frame
+    public ZstdCompressCtx reset(ZstdResetDirective directive) {
+        Objects.requireNonNull(directive, "directive");
+        NativeCall.checkReturnValue(() -> (long) Bindings.CCTX_RESET.invokeExact(ptr(), directive.value()));
+        if (directive != ZstdResetDirective.SESSION_ONLY) {
+            this.level = Zstd.defaultCompressionLevel();
+        }
+        return this;
+    }
+
     /// Compresses `src` into a new zstd frame using this context and its
     /// advanced parameters.
     ///

zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressCtx.java

@@ -49,6 +49,25 @@ public ZstdDecompressCtx windowLogMax(int windowLogMax) {
         return parameter(ZstdDecompressParameter.WINDOW_LOG_MAX, windowLogMax);
     }
 
+    /// Resets this context so it can be reused for the next frame without the
+    /// cost of freeing and recreating its native state.
+    ///
+    /// - [ZstdResetDirective#SESSION_ONLY] aborts the current frame and drops
+    ///   buffered state, keeping all parameters and any dictionary.
+    /// - [ZstdResetDirective#PARAMETERS] and
+    ///   [ZstdResetDirective#SESSION_AND_PARAMETERS] also restore every
+    ///   parameter to its default and clear the dictionary. Only valid when no
+    ///   frame is in progress.
+    ///
+    /// @param directive what to clear
+    /// @return `this`, for chaining
+    /// @throws ZstdException if a parameter reset is requested mid-frame
+    public ZstdDecompressCtx reset(ZstdResetDirective directive) {
+        Objects.requireNonNull(directive, "directive");
+        NativeCall.checkReturnValue(() -> (long) Bindings.DCTX_RESET.invokeExact(ptr(), directive.value()));
+        return this;
+    }
+
     /// Decompresses a frame into a buffer of at most `maxSize` bytes.
     ///
     /// @param compressed a complete zstd frame

zstd/src/main/java/io/github/dfa1/zstd/ZstdResetDirective.java

@@ -0,0 +1,28 @@
+package io.github.dfa1.zstd;
+
+/// Selects what a context reset clears, mirroring `ZSTD_ResetDirective`.
+///
+/// Use it with [ZstdCompressCtx#reset(ZstdResetDirective)] and
+/// [ZstdDecompressCtx#reset(ZstdResetDirective)] to recycle a context for the
+/// next frame without freeing and recreating its native state.
+public enum ZstdResetDirective {
+
+    /// Abort the current frame and discard any unflushed data, keeping all
+    /// parameters and the loaded dictionary. Cheap; use it between frames.
+    SESSION_ONLY(1),
+    /// Restore every parameter to its default and clear the dictionary. Only
+    /// valid when no frame is in progress.
+    PARAMETERS(2),
+    /// Do both: reset the session and the parameters in one call.
+    SESSION_AND_PARAMETERS(3);
+
+    private final int value;
+
+    ZstdResetDirective(int value) {
+        this.value = value;
+    }
+
+    int value() {
+        return value;
+    }
+}

zstd/src/test/java/io/github/dfa1/zstd/ZstdParameterTest.java

@@ -143,6 +143,71 @@ void rejectsOutOfRangeValue() {
         }
     }
 
+    @Nested
+    class Reset {
+
+        @Test
+        void sessionOnlyKeepsLevelAndParameters() {
+            // Given a context used once, then reset for the session only
+            byte[] reused;
+            byte[] fresh;
+            try (ZstdCompressCtx sut = new ZstdCompressCtx().level(19)) {
+                sut.compress(PAYLOAD);
+                sut.reset(ZstdResetDirective.SESSION_ONLY);
+                reused = sut.compress(PAYLOAD);
+            }
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().level(19)) {
+                fresh = ctx.compress(PAYLOAD);
+            }
+
+            // Then the level survives the reset: the next frame matches a fresh level-19 frame
+            assertThat(reused).isEqualTo(fresh);
+        }
+
+        @Test
+        void sessionAndParametersRestoresTheDefaultLevel() {
+            // Given a level-19 context reset with parameters cleared
+            byte[] afterReset;
+            byte[] atDefault;
+            try (ZstdCompressCtx sut = new ZstdCompressCtx().level(19)) {
+                sut.compress(PAYLOAD);
+                sut.reset(ZstdResetDirective.SESSION_AND_PARAMETERS);
+                afterReset = sut.compress(PAYLOAD);
+            }
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx()) {
+                atDefault = ctx.compress(PAYLOAD);
+            }
+
+            // Then the level falls back to the default, matching a fresh default-level frame
+            assertThat(afterReset).isEqualTo(atDefault);
+        }
+
+        @Test
+        void decompressContextStillDecodesAfterReset() {
+            // Given a decompression context reset between frames
+            byte[] frame = Zstd.compress(PAYLOAD);
+            try (ZstdDecompressCtx sut = new ZstdDecompressCtx()) {
+                sut.decompress(frame, PAYLOAD.length);
+                sut.reset(ZstdResetDirective.SESSION_AND_PARAMETERS);
+
+                // Then the next frame still decodes
+                assertThat(sut.decompress(frame, PAYLOAD.length)).isEqualTo(PAYLOAD);
+            }
+        }
+
+        @Test
+        void rejectsNullDirective() {
+            // Given a compression context
+            try (ZstdCompressCtx sut = new ZstdCompressCtx()) {
+                // When reset with a null directive
+                ThrowingCallable result = () -> sut.reset(null);
+
+                // Then it fails fast
+                assertThatThrownBy(result).isInstanceOf(NullPointerException.class);
+            }
+        }
+    }
+
     @Nested
     class GenericSetter {