diff --git a/adr/0001-ffm-over-jni.md b/adr/0001-ffm-over-jni.md index b75af5e..b486688 100644 --- a/adr/0001-ffm-over-jni.md +++ b/adr/0001-ffm-over-jni.md @@ -32,8 +32,8 @@ Native symbols bind to `MethodHandle`s in `Bindings`; the library targets JDK `--enable-native-access`. ### Risks to manage -- FFM is young; signatures/restrictions may evolve. Centralised in `Bindings` - and `NativeCall` so changes are localised. +- FFM is young; signatures/restrictions may evolve. Centralized in `Bindings` + and `NativeCall` so changes are localized. ## Alternatives considered diff --git a/adr/0002-zig-cc-native-build.md b/adr/0002-zig-cc-native-build.md index 11e94ff..64f17c2 100644 --- a/adr/0002-zig-cc-native-build.md +++ b/adr/0002-zig-cc-native-build.md @@ -31,7 +31,7 @@ it is idempotent (skips if the library exists). - `zig cc` is a clang wrapper, not the zstd-blessed build path. ### Risks to manage -- Zig is pre-1.0; `zig cc` flag behaviour can shift between versions. The Zig +- Zig is pre-1.0; `zig cc` flag behavior can shift between versions. The Zig version is **pinned** (0.16.0) in CI; upgrades require a re-test. ## Alternatives considered diff --git a/adr/0009-nativeobject-idempotent-close.md b/adr/0009-nativeobject-idempotent-close.md index bfac3ed..4a6dc3f 100644 --- a/adr/0009-nativeobject-idempotent-close.md +++ b/adr/0009-nativeobject-idempotent-close.md @@ -8,7 +8,7 @@ Native contexts and dictionaries (CCtx, DCtx, CDict, DDict) own off-heap memory that must be freed via their zstd `ZSTD_free*` calls. Java's GC does not free -native memory; double-free is undefined behaviour. The lifecycle model must be +native memory; double-free is undefined behavior. The lifecycle model must be deterministic and safe to call twice. ## Decision diff --git a/adr/0012-benchmark-methodology.md b/adr/0012-benchmark-methodology.md index 788cde5..74e3dad 100644 --- a/adr/0012-benchmark-methodology.md +++ b/adr/0012-benchmark-methodology.md @@ -18,14 +18,14 @@ Benchmarks live in the `benchmark/` module (JMH), comparing zstd-java Two payload families: -- **Synthetic, semi-compressible** (`BenchData`, ~3x ratio) parameterised over +- **Synthetic, semi-compressible** (`BenchData`, ~3x ratio) parameterized over *sizes* — exercises the bandwidth regime. -- **The vendored golden corpus** (`GoldenCorpusBenchmark`) parameterised over +- **The vendored golden corpus** (`GoldenCorpusBenchmark`) parameterized over *real files* — exercises per-call native-boundary overhead, where FFM-vs-JNI fixed costs show up. Published numbers in `docs/benchmarks.md` state the host, JDK, dependency -versions, and the JMH run parameters. Quick low-iteration runs are labelled +versions, and the JMH run parameters. Quick low-iteration runs are labeled **directional, not publication-grade**; publication numbers use higher fork and iteration counts. diff --git a/docs/how-to.md b/docs/how-to.md index 4a9e728..ccdee8a 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -5,7 +5,7 @@ Task-focused recipes. Each assumes you have the library on the classpath (see th ## Compress on a hot path -Reuse a context to amortise native allocation across many calls: +Reuse a context to amortize native allocation across many calls: ```java try (ZstdCompressContext cctx = new ZstdCompressContext().level(19); @@ -39,7 +39,7 @@ try (ZstdCompressContext cctx = new ZstdCompressContext().level(19)) { } ``` -`ZstdDecompressContext.reset(...)` works the same way. Reuse alone amortises +`ZstdDecompressContext.reset(...)` works the same way. Reuse alone amortizes allocation; reset lets a long-lived or pooled context return to a known state without churning native memory. diff --git a/docs/supported.md b/docs/supported.md index 14be6f1..6cd80ac 100644 --- a/docs/supported.md +++ b/docs/supported.md @@ -82,7 +82,7 @@ rather than the deprecated `ZSTD_getDecompressedSize`. 1. ~~**Streaming**~~ — done: `ZstdOutputStream` / `ZstdInputStream` (`compressStream2`, `decompressStream`, bounded buffers, dictionary constructors, `pledgedSrcSize` via `withPledgedSize`). Remaining: `MemorySegment`-buffer driver. 2. ~~**Advanced parameters**~~ — done: every `ZSTD_cParameter`/`ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter` (+ `bounds()`), on both contexts; `pledgedSrcSize`. `nbWorkers` is settable but inert until the native build enables multithreading. 3. ~~**Frame inspection**~~ — done: `ZstdFrame` (`isFrame`, `header`, `compressedSize`, `decompressedBound`, `decompressedSize`, `dictId`, skippable, `getFrameProgression`); dict-id from raw/CDict/DDict. -4. ~~**Better dictionaries**~~ — done: COVER / fast-COVER optimisers, `finalizeDictionary`, `getDictHeaderSize`. +4. ~~**Better dictionaries**~~ — done: COVER / fast-COVER optimizers, `finalizeDictionary`, `getDictHeaderSize`. 5. ~~**Typed errors**~~ — done: `ZstdException.code()` returns `ZstdErrorCode` (via `getErrorCode`). ## Full symbol table diff --git a/integration-tests/src/test/java/io/github/dfa1/zstd/it/GoldenCorpusTest.java b/integration-tests/src/test/java/io/github/dfa1/zstd/it/GoldenCorpusTest.java index e85a516..d8692c5 100644 --- a/integration-tests/src/test/java/io/github/dfa1/zstd/it/GoldenCorpusTest.java +++ b/integration-tests/src/test/java/io/github/dfa1/zstd/it/GoldenCorpusTest.java @@ -52,7 +52,7 @@ private static Path locateCorpus() { } throw new IllegalStateException( "golden corpus not found: third_party/zstd/tests is missing — " - + "initialise the zstd submodule (git submodule update --init --recursive)"); + + "initialize the zstd submodule (git submodule update --init --recursive)"); } private static Stream filesIn(String subdir, String suffix) { diff --git a/integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdInteropExtrasTest.java b/integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdInteropExtrasTest.java index 3a9948f..529ee32 100644 --- a/integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdInteropExtrasTest.java +++ b/integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdInteropExtrasTest.java @@ -115,7 +115,7 @@ void javaRejectsCorruptedChecksum() { } /// Skippable frames carry application metadata the decoder must pass over. A - /// skippable frame written by this library must be recognised and skipped by + /// skippable frame written by this library must be recognized and skipped by /// the zstd-jni stream decoder, leaving the following real frame intact. @Nested class Skippable { diff --git a/zstd/src/main/java/io/github/dfa1/zstd/Bindings.java b/zstd/src/main/java/io/github/dfa1/zstd/Bindings.java index 29514fb..8bd41f8 100644 --- a/zstd/src/main/java/io/github/dfa1/zstd/Bindings.java +++ b/zstd/src/main/java/io/github/dfa1/zstd/Bindings.java @@ -13,7 +13,7 @@ /// Signatures and semantics follow the /// [official manual](https://facebook.github.io/zstd/doc/api_manual_latest.html). /// -/// `size_t` and `unsigned long long` are modelled as +/// `size_t` and `unsigned long long` are modeled as /// [java.lang.foreign.ValueLayout#JAVA_LONG] (LP64); the public API guards /// against negative interpretations where zstd uses sentinel values. /// diff --git a/zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressContext.java b/zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressContext.java index 00bd34f..6bafc87 100644 --- a/zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressContext.java +++ b/zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressContext.java @@ -6,7 +6,7 @@ /// A reusable compression context. /// -/// Reusing one context across many [#compress] calls amortises native +/// Reusing one context across many [#compress] calls amortizes native /// state allocation, making it cheaper than the stateless [Zstd#compress] /// on hot paths. Not thread-safe: confine an instance to one thread or pool it. /// diff --git a/zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressContext.java b/zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressContext.java index 23934f6..767a65d 100644 --- a/zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressContext.java +++ b/zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressContext.java @@ -6,7 +6,7 @@ /// A reusable decompression context. /// -/// Reusing one context across many [#decompress] calls amortises native +/// Reusing one context across many [#decompress] calls amortizes native /// state allocation. Not thread-safe: confine an instance to one thread or pool it. public final class ZstdDecompressContext extends NativeObject { diff --git a/zstd/src/main/java/io/github/dfa1/zstd/ZstdDictionary.java b/zstd/src/main/java/io/github/dfa1/zstd/ZstdDictionary.java index f237e8f..c621366 100644 --- a/zstd/src/main/java/io/github/dfa1/zstd/ZstdDictionary.java +++ b/zstd/src/main/java/io/github/dfa1/zstd/ZstdDictionary.java @@ -123,7 +123,7 @@ public static ZstdDictionary trainCover(List samples, int maxDictBytes) return trainCover(samples, maxDictBytes, 0); } - /// Trains a COVER dictionary optimised for a specific compression level. + /// Trains a COVER dictionary optimized for a specific compression level. /// /// @param samples representative payloads to learn from /// @param maxDictBytes upper bound on the produced dictionary size @@ -135,7 +135,7 @@ public static ZstdDictionary trainCover(List samples, int maxDictBytes, } /// Trains a dictionary with the fast COVER algorithm, auto-tuning its - /// parameters. The recommended optimiser: nearly the quality of + /// parameters. The recommended optimizer: nearly the quality of /// [#trainCover] at a fraction of the time. /// /// @param samples representative payloads to learn from @@ -146,7 +146,7 @@ public static ZstdDictionary trainFastCover(List samples, int maxDictByt return trainFastCover(samples, maxDictBytes, 0); } - /// Trains a fast COVER dictionary optimised for a specific compression level. + /// Trains a fast COVER dictionary optimized for a specific compression level. /// /// @param samples representative payloads to learn from /// @param maxDictBytes upper bound on the produced dictionary size @@ -184,19 +184,19 @@ private static ZstdDictionary optimize(List samples, int maxDictBytes, /// Turns raw dictionary `content` you supply (e.g. hand-picked common bytes, /// or a prefix from elsewhere) into a usable zstd dictionary by adding a /// header and entropy tables tuned on `samples`. Use this when you control the - /// dictionary content and only want zstd to finalise it. + /// dictionary content and only want zstd to finalize it. /// /// @param content the raw dictionary content to wrap /// @param samples representative payloads to tune entropy tables on /// @param maxDictBytes upper bound on the produced dictionary size /// @param compressionLevel the level the dictionary will be used at (0 = default) - /// @return the finalised dictionary - /// @throws ZstdException if finalisation fails + /// @return the finalized dictionary + /// @throws ZstdException if finalization fails public static ZstdDictionary finalizeFrom(byte[] content, List samples, int maxDictBytes, int compressionLevel) { Objects.requireNonNull(content, "content"); Objects.requireNonNull(samples, SAMPLES); - requireNonEmpty(samples, "finalise"); + requireNonEmpty(samples, "finalize"); try (Arena arena = Arena.ofConfined()) { FlatSamples in = flatten(arena, samples); MemorySegment contentSeg = Zstd.copyIn(arena, content); @@ -211,7 +211,7 @@ public static ZstdDictionary finalizeFrom(byte[] content, List samples, } catch (Throwable t) { throw NativeCall.rethrow(t); } - return toDictionary(dictBuf, produced, "dictionary finalisation"); + return toDictionary(dictBuf, produced, "dictionary finalization"); } } @@ -283,7 +283,7 @@ public int headerSize() { } } - /// Serialises this dictionary to a fresh byte array. + /// Serializes this dictionary to a fresh byte array. /// /// @return a copy of the raw dictionary bytes, suitable for persisting public byte[] toByteArray() { diff --git a/zstd/src/main/java/io/github/dfa1/zstd/ZstdEndDirective.java b/zstd/src/main/java/io/github/dfa1/zstd/ZstdEndDirective.java index c3ad52d..8723c72 100644 --- a/zstd/src/main/java/io/github/dfa1/zstd/ZstdEndDirective.java +++ b/zstd/src/main/java/io/github/dfa1/zstd/ZstdEndDirective.java @@ -1,6 +1,6 @@ package io.github.dfa1.zstd; -/// Controls how much a [ZstdCompressStream#compress] call finalises, mirroring +/// Controls how much a [ZstdCompressStream#compress] call finalizes, mirroring /// `ZSTD_EndDirective`. public enum ZstdEndDirective { diff --git a/zstd/src/main/java/io/github/dfa1/zstd/ZstdErrorCode.java b/zstd/src/main/java/io/github/dfa1/zstd/ZstdErrorCode.java index 37c8e10..11d8af7 100644 --- a/zstd/src/main/java/io/github/dfa1/zstd/ZstdErrorCode.java +++ b/zstd/src/main/java/io/github/dfa1/zstd/ZstdErrorCode.java @@ -9,7 +9,7 @@ /// /// The numeric values mirror `ZSTD_ErrorCode` in the vendored zstd header. zstd /// does not guarantee these values across versions, but this library pins a -/// specific zstd source, so they are stable for a given release. An unrecognised +/// specific zstd source, so they are stable for a given release. An unrecognized /// code maps to [#UNKNOWN]. public enum ZstdErrorCode { @@ -19,7 +19,7 @@ public enum ZstdErrorCode { NO_ERROR(0), /// Unspecified error. GENERIC(1), - /// Input does not start with a recognised zstd frame prefix. + /// Input does not start with a recognized zstd frame prefix. PREFIX_UNKNOWN(10), /// Frame requires an unsupported zstd version. VERSION_UNSUPPORTED(12), @@ -57,7 +57,7 @@ public enum ZstdErrorCode { STABILITY_CONDITION_NOT_RESPECTED(50), /// Operation called at the wrong stage of the context lifecycle. STAGE_WRONG(60), - /// Context was not initialised before use. + /// Context was not initialized before use. INIT_MISSING(62), /// A memory allocation failed. MEMORY_ALLOCATION(64), @@ -116,7 +116,7 @@ public String description() { /// Maps a native `ZSTD_ErrorCode` integer to its category. /// /// @param value the native error code - /// @return the matching category, or [#UNKNOWN] if unrecognised + /// @return the matching category, or [#UNKNOWN] if unrecognized static ZstdErrorCode of(int value) { for (ZstdErrorCode code : values()) { if (code.value == value) { diff --git a/zstd/src/test/java/io/github/dfa1/zstd/NativeLibraryTest.java b/zstd/src/test/java/io/github/dfa1/zstd/NativeLibraryTest.java index e308be1..a8f5bd8 100644 --- a/zstd/src/test/java/io/github/dfa1/zstd/NativeLibraryTest.java +++ b/zstd/src/test/java/io/github/dfa1/zstd/NativeLibraryTest.java @@ -26,7 +26,7 @@ class Classifier { "Windows 11, amd64, windows-x86_64", "Windows 11, aarch64, windows-aarch64", "Linux, x86_64, linux-x86_64", - // unknown os falls back to linux; arch aliases normalise + // unknown os falls back to linux; arch aliases normalize "FreeBSD, aarch64, linux-aarch64", "Linux, amd64, linux-x86_64", "Linux, arm64, linux-aarch64", diff --git a/zstd/src/test/java/io/github/dfa1/zstd/ZstdDictionaryTest.java b/zstd/src/test/java/io/github/dfa1/zstd/ZstdDictionaryTest.java index 7e5d64d..b012178 100644 --- a/zstd/src/test/java/io/github/dfa1/zstd/ZstdDictionaryTest.java +++ b/zstd/src/test/java/io/github/dfa1/zstd/ZstdDictionaryTest.java @@ -127,7 +127,7 @@ void trainedDictionaryHasHeader() { @Test void finalizeFailsWithoutSamples() { - // When finalising raw content with no tuning samples + // When finalizing raw content with no tuning samples ThrowingCallable result = () -> ZstdDictionary.finalizeFrom(new byte[]{1, 2, 3}, List.of(), 4096, 0); // Then it fails fast with the empty-samples guard @@ -320,11 +320,11 @@ void factoryDictionariesRoundTrip() { } @Nested - class Serialisation { + class Serialization { @Test void reloadedDictionaryKeepsIdentityAndDecodes() { - // Given the dictionary serialised and reloaded + // Given the dictionary serialized and reloaded ZstdDictionary reloaded = ZstdDictionary.of(sut.toByteArray()); // Then it carries the same dictionary id diff --git a/zstd/src/test/java/io/github/dfa1/zstd/ZstdFrameTest.java b/zstd/src/test/java/io/github/dfa1/zstd/ZstdFrameTest.java index 62ad638..87a95fe 100644 --- a/zstd/src/test/java/io/github/dfa1/zstd/ZstdFrameTest.java +++ b/zstd/src/test/java/io/github/dfa1/zstd/ZstdFrameTest.java @@ -24,7 +24,7 @@ class ZstdFrameTest { class IsFrame { @Test - void recognisesAZstdFrame() { + void recognizesAZstdFrame() { assertThat(ZstdFrame.isZstdFrame(Zstd.compress(PAYLOAD))).isTrue(); } @@ -323,7 +323,7 @@ void roundTripsContentAndMagicVariant() { byte[] meta = "sidecar metadata".getBytes(StandardCharsets.UTF_8); byte[] frame = ZstdFrame.writeSkippableFrame(meta, 7); - // Then it is recognised as skippable and decodes back with its variant + // Then it is recognized as skippable and decodes back with its variant assertThat(ZstdFrame.isSkippableFrame(frame)).isTrue(); assertThat(ZstdFrame.header(frame).frameType()).isEqualTo(ZstdFrameType.SKIPPABLE); @@ -430,7 +430,7 @@ void mirrorTheByteArrayOverloadsForANativeFrame() { } @Test - void recognisesASkippableNativeFrame() { + void recognizesASkippableNativeFrame() { // Given a skippable frame in a native segment byte[] frame = ZstdFrame.writeSkippableFrame("meta".getBytes(StandardCharsets.UTF_8), 5); try (Arena arena = Arena.ofConfined()) {