Skip to content

perf(cpp): batch decode for GORILLA_V1 float and double - #1112

Merged
ColinLeeo merged 2 commits into
apache:developfrom
ColinLeeo:perf/cpp-gorilla-v1-batch-decode
Nov 16, 2026
Merged

ColinLeeo merged 2 commits into
apache:developfrom
ColinLeeo:perf/cpp-gorilla-v1-batch-decode

Conversation

@ColinLeeo

Copy link
Copy Markdown
Contributor

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_double and skip_float / skip_double to
FloatGorillaV1Decoder / DoubleGorillaV1Decoder.

On a wrapped ByteStream the batch decodes straight from the wrapped buffer
through a 64-bit bit reservoir (GorillaBitReader, the same reader the GORILLA
codec uses) instead of ByteStream::read_buf per byte plus a per-bit scalar
loop 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:

  • the one-value lookahead is preserved; the NaN sentinel that flush() appends
    is never returned as a value, and on it the batch stops and latches is_end_;
  • all decoder state survives across calls (flag_, pre_value_, leading /
    trailing zeros, is_end_, latched error, byte/bit cursor), so a batch that
    stops at capacity or at a page end resumes correctly in the next
    read_batch_* / read_float / read_double;
  • a truncated stream returns the same error (E_BUF_NOT_ENOUGH, or
    E_DECODE_ERR for a short first value) and emits the same values as the
    per-value loop;
  • zero capacity and capacity beyond the remaining values behave like the base
    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 <<= 32 on float, <<= 64 on double). The three shift sites (both
scalar decoders and the new raw one) now skip the shift when len == 0, where
the 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 wrapped
stream; outputs are compared bit for bit and match.

type pattern old values/s new values/s speedup
FLOAT smooth 34.5 M 146.5 M 4.25x
FLOAT high-entropy 27.3 M 161.3 M 5.90x
FLOAT constant 278.1 M 653.9 M 2.35x
DOUBLE smooth 18.4 M 141.1 M 7.68x
DOUBLE high-entropy 15.7 M 145.7 M 9.30x
DOUBLE constant 263.5 M 654.0 M 2.48x

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):

  • Java wire-format golden streams generated with SinglePrecisionEncoderV1 /
    DoublePrecisionEncoderV1 (two and three values, single value, empty stream,
    leading NaN, double max/denormal, -0.0); the C++ encoder output is asserted
    equal to the Java bytes and both C++ decode paths decode them;
  • per-value vs batch parity over random, smooth, repeated, constant,
    ±Inf / -0.0 / subnormal / single-value data with capacities 1..1e6 and mixed
    cycles that split the stream at arbitrary points;
  • every truncated prefix of several streams (same return code and values);
  • zero capacity, capacity beyond the stream, repeated calls after the end,
    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: BUILD
    SUCCESS (Java, C++ ctest 100% passed, Python).
  • ./mvnw spotless:check -P with-java,with-python: pass.
  • Full C++ suite under ASan+UBSan (-DENABLE_ASAN=ON,
    -DTSFILE_SANITIZER_CHECKS=address,undefined, RelWithDebInfo, LeakSanitizer
    on) 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).

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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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;

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The float and double skip paths underreport consumed values on batch errors because they return before adding successfully decoded values to skipped.

2 open issues

Review effort: Balanced

…atch-decode-76ffff

# Conflicts:
#	cpp/CMakeLists.txt
@ColinLeeo
ColinLeeo merged commit 6dbffcc into apache:develop Nov 16, 2026
40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add batch decode for RLE (FLOAT/DOUBLE) and GORILLA_V1 encodings

2 participants