Repository navigation
perf(cpp): batch decode for GORILLA_V1 float and double - #1112
Merged
ColinLeeo merged 2 commits intoNov 16, 2026
Merged
Conversation
Add read_batch_float/read_batch_double overrides to the GORILLA_V1 decoders. On a wrapped ByteStream they decode through a 64-bit bit reservoir over the wrapped buffer instead of ByteStream::read_buf per byte, while preserving the per-value lookahead: the NaN sentinel is never returned as a value, all decoder state survives across calls, and a batch that stops mid-stream resumes correctly in the next read_batch_*/read_float/read_double. Non-wrapped streams fall back to the per-value loop. skip_float/skip_double reuse the batch path. Measured with cpp/bench_mark/gorilla_v1_batch_decode_benchmark on 4 Mi values (best of 5): DOUBLE 7.7x (smooth), 9.3x (high entropy), 2.5x (constant); FLOAT 4.3x, 5.9x, 2.4x. Both paths produce identical bit patterns. Tests cover Java-generated golden streams, per-value/batch parity over random, smooth, repeated, constant, special (±Inf, -0.0, subnormals) and single-value data under many batch capacities, every truncated prefix, zero capacity, capacity beyond the stream, scalar/batch handoffs, skipping, and the unwrapped fallback. Completes the GORILLA_V1 half of issue apache#1071; the RLE half landed in PR apache#1078.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Truncated input can leave the decoder cursor short of the stream end, causing repeated errors, while skip operations underreport values consumed before an error.
2 open issues
What changed in this PR
Adds buffered batch decoding for C++ GORILLA_V1 FLOAT and DOUBLE values, completing the remaining codec work from #1071 after the RLE changes in #1078.
Changes:
- Adds wrapped-buffer batch reads and skip overrides, with scalar fallback for non-wrapped streams.
- Adds Java golden-stream checks and regression coverage for decoding, truncation, handoffs, and page resets.
- Adds a benchmark and build instructions comparing scalar and batch throughput.
| File | Description |
|---|---|
cpp/test/encoding/gorilla_v1_codec_test.cc |
Adds compatibility and batch-decoding regression tests. |
cpp/src/encoding/gorilla_v1_decoder.h |
Implements batch reads and skips; guards zero-length XOR shifts. |
cpp/CMakeLists.txt |
Registers the optional GORILLA_V1 benchmark target. |
cpp/bench_mark/README.md |
Documents benchmark usage and defaults. |
cpp/bench_mark/gorilla_v1_batch_decode_benchmark.cc |
Compares scalar and batch performance with bitwise output checks. |
Review effort: Balanced
Comment on lines
+309
to
+310
| const uint64_t consumed_bits = | ||
| static_cast<uint64_t>(r.pos) * 8 - static_cast<uint64_t>(r.bits); |
Comment on lines
+400
to
+403
| if (ret != common::E_OK) { | ||
| return ret; | ||
| } | ||
| skipped += got; |
…atch-decode-76ffff # Conflicts: # cpp/CMakeLists.txt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

What changes
GORILLA_V1 was the last value codec without a batch path (RLE FLOAT/DOUBLE
landed in #1078; Plain, GORILLA and TS_2DIFF already had one). This adds
read_batch_float/read_batch_doubleandskip_float/skip_doubletoFloatGorillaV1Decoder/DoubleGorillaV1Decoder.On a wrapped
ByteStreamthe batch decodes straight from the wrapped bufferthrough a 64-bit bit reservoir (
GorillaBitReader, the same reader the GORILLAcodec uses) instead of
ByteStream::read_bufper byte plus a per-bit scalarloop and a virtual call per value. Non-wrapped streams keep the per-value loop.
The encoding is not SIMD-friendly (every value is variable-length and depends
on the previous one), so this is a buffered batch decode, not a vectorized one.
Semantics
The per-value path is untouched and the wire format is unchanged. The batch
reproduces it exactly:
flush()appendsis never returned as a value, and on it the batch stops and latches
is_end_;flag_,pre_value_, leading /trailing zeros,
is_end_, latched error, byte/bit cursor), so a batch thatstops at
capacityor at a page end resumes correctly in the nextread_batch_*/read_float/read_double;E_BUF_NOT_ENOUGH, orE_DECODE_ERRfor a short first value) and emits the same values as theper-value loop;
implementation.
One deliberate difference: after an embedded (mid-stream) NaN, the scalar
decoder's byte-refill logic can shift by a negative count, which is undefined
behaviour; the batch stops at the marker instead of following that path. The
production readers only contain a sentinel at the end of a page payload, where
both paths behave identically.
UBSan also exposed a pre-existing shift-by-type-width in the same XOR code
(truncated input whose leading/len fields both decode to 0 makes
xor_value <<= 32on float,<<= 64on double). The three shift sites (bothscalar decoders and the new raw one) now skip the shift when
len == 0, wherethe xor payload is empty and the result is 0 either way. No change for
well-formed streams.
Benchmark
cpp/bench_mark/gorilla_v1_batch_decode_benchmark.cc(new,BUILD_BENCHMARK=ON). 4 Mi values, best of 5, Apple Silicon Release build."Old" is the base
Decoder::read_batch_*per-value loop on the same wrappedstream; outputs are compared bit for bit and match.
The repeated-value case gains least (2.4x) because the old loop already spent
one bit per repeated value; the XOR-carrying cases gain most.
Tests
New
cpp/test/encoding/gorilla_v1_codec_test.cc(29 cases):SinglePrecisionEncoderV1/DoublePrecisionEncoderV1(two and three values, single value, empty stream,leading NaN,
doublemax/denormal, -0.0); the C++ encoder output is assertedequal to the Java bytes and both C++ decode paths decode them;
±Inf / -0.0 / subnormal / single-value data with capacities 1..1e6 and mixed
cycles that split the stream at arbitrary points;
scalar-to-batch and batch-to-scalar handoffs, skip parity (including skipping
past the end), the unwrapped fallback, decoder reset between pages, and the
embedded-NaN stop.
Verification
./mvnw clean verify -P with-java,with-python -Denable.lzma2=ON: BUILDSUCCESS (Java, C++ ctest 100% passed, Python).
./mvnw spotless:check -P with-java,with-python: pass.-DENABLE_ASAN=ON,-DTSFILE_SANITIZER_CHECKS=address,undefined, RelWithDebInfo, LeakSanitizeron) on Ubuntu 20.04 / GCC 9.4: 1566/1566 tests pass, no sanitizer reports.
That host has CMake 3.16 and no system liblzma, so LZMA2 was off there; the
macOS builds above ran with
-Denable.lzma2=ON.Closes #1071 (the RLE half landed in #1078).