Repository navigation
perf(cpp): batch decode for the SPRINTZ codec - #1110
Conversation
SPRINTZ served values one at a time: each read_* returned a single value from the decoded block, and readers reach the codec through read_exact_*, whose batch path looped over those per-value calls. A 129-value page cost 129 virtual calls. Add read_batch_int32/int64/float/double overrides that copy whole runs of already-reconstructed values out of the block buffer and decode the next blocks in place. SprintzDecoder::batch_read mirrors the per-value state machine exactly, including the has_remaining() gate that stops INT32/INT64 before a full block's last value when no data follows, so batch and scalar reads interleave freely and stop at the same points. While touching decode_block, remove its per-block allocations: the packed payload buffer and the unpack scratch buffer become members, and the packer is created once and re-set per width instead of being re-allocated through make_shared. Packed values are unpacked straight into the block buffer, and the unread tail of a short read is re-zeroed so a reused buffer matches the old freshly-zeroed allocation byte for byte. FLOAT/DOUBLE also stop shadowing the base class's current_count_, decode_size_ and is_block_read_ members. Measured on Apple Silicon (Release, 2M values, capacity 129, best of 5, parent commit built with identical flags): per-value decode, after vs before: 1.9-2.1x batch over per-value on the new code: 1.38-1.71x overall vs the original decoder: 3.1-3.9x (e.g. INT32 smooth 107M -> 330M values/s) 40 new tests in cpp/test/encoding/sprintz_codec_test.cc compare the batch overrides against the per-value loop they replace, for all four types: smooth, high-entropy, constant and jump streams; block-boundary capacities; random capacity scripts; zero and negative capacity; end of stream; every truncated prefix of a stream; small ByteStream page sizes that split block payload reads; and read_exact in chunks. Adds cpp/bench_mark/sprintz_batch_decode_benchmark.cc (BUILD_BENCHMARK=ON).
There was a problem hiding this comment.
🔵 Needs a closer look
SPRINTZ buffer and batch-state changes lack cross-language fixture validation, and scalar/batch parity tests share the modified decode_block(), so they cannot independently establish compatibility.
No open issues 🎉
What changed in this PR
This PR improves C++ SPRINTZ decoding throughput by adding batch reads and removing per-block allocations, while preserving scalar-read behavior and the existing on-disk format.
Changes:
- Adds a shared batch-decoding helper and overrides for all four numeric types.
- Reuses packed-data buffers and packers, and consolidates floating-point decoder state.
- Adds 40 regression tests and a benchmark comparing batch and per-value decoding.
| File | Description |
|---|---|
cpp/test/encoding/sprintz_codec_test.cc |
Adds batch parity, boundary, truncation, and exact-read tests. |
cpp/src/encoding/sprintz_decoder.h |
Adds the shared batch-read state machine. |
cpp/src/encoding/int64_sprintz_decoder.h |
Adds INT64 batch reads and reusable decoding storage. |
cpp/src/encoding/int32_sprintz_decoder.h |
Adds INT32 batch reads and reusable decoding storage. |
cpp/src/encoding/float_sprintz_decoder.h |
Adds FLOAT batch reads, reuses storage, and removes shadowed state. |
cpp/src/encoding/double_sprintz_decoder.h |
Adds DOUBLE batch reads, reuses storage, and removes shadowed state. |
cpp/CMakeLists.txt |
Registers the optional SPRINTZ decoding benchmark. |
cpp/bench_mark/sprintz_batch_decode_benchmark.cc |
Compares batch and per-value throughput across types and data patterns. |
Review effort: Balanced
The batch/scalar parity tests share decode_block(), so they cannot by themselves show that the C++ decoder still reads bytes another implementation wrote. Add six golden streams produced by the Java encoders (IntSprintzEncoder, LongSprintzEncoder, FloatSprintzEncoder, DoubleSprintzEncoder; default "fire" predictor): a first block with a short tail, a constant run, a stream that crosses the encoder's 16-group flush and ends in a short block, epoch-millisecond timestamps, and smooth FLOAT/DOUBLE series. For each fixture the test asserts that the C++ encoder emits the same bytes for the same values, then decodes the Java bytes three ways: read_exact (batch plus its scalar handoff), a pure per-value drain, and a batch drain with capacities that split blocks at arbitrary points. FLOAT/DOUBLE expected values are built from Java's raw bit patterns so the comparison is bit-exact.
|
Added cross-language validation for the concern that the scalar/batch parity tests share the modified |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1110 +/- ##
===========================================
+ Coverage 66.89% 66.90% +0.01%
===========================================
Files 788 788
Lines 57630 57667 +37
Branches 9310 9320 +10
===========================================
+ Hits 38551 38583 +32
- Misses 17399 17409 +10
+ Partials 1680 1675 -5 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
What
Batch decoding for the C++ SPRINTZ codec, plus removal of its per-block allocations. Encoding, the block format and the on-disk representation are unchanged; this is decode-only.
SPRINTZ served values one at a time:
read_int32/read_int64/read_float/read_doublereturned a single value from the decoded block, and readers reach the codec throughread_exact_*, whose batch path looped over those per-value calls. A 129-value page therefore cost 129 virtual calls.Changes
cpp/src/encoding/sprintz_decoder.h: new protectedSprintzDecoder::batch_read<T>(). It copies runs of already-reconstructed values out of the block buffer, decodes the next block when the buffer is exhausted, and reproduces the per-value state machine exactly.read_batch_int32/int64/float/doubleon top of that helper.decode_block()no longer allocates per block: the packed payload buffer and the unpack scratch buffer are members, the packer is constructed once and re-set withset_width()instead ofstd::make_sharedper block, and values unpack straight into the block buffer. A short read's unread tail is re-zeroed so the reused buffer is byte-identical to the old freshly-zeroed allocation.FloatSprintzDecoder/DoubleSprintzDecoderno longer shadow the base class'scurrent_count_/decode_size_/is_block_read_members.A subtlety the batch path has to preserve
A full SPRINTZ block decodes to
block_size_ + 1= 9 values (the block's first value stored verbatim, eight reconstructed from packed deltas).Int32SprintzDecoder/Int64SprintzDecoder::has_remaining()report a pending block as readable only whilecurrent_count_ < block_size_, so a per-value drain of a stream that ends exactly on a full block drops its last value;read_exact_*recovers it through its scalarread_onefallback.FloatSprintzDecoder/DoubleSprintzDecodercompare againstdecode_size_and always emit it. The batch loop mirrors both behaviours rather than "fixing" them, so batch and scalar reads interleave freely and stop at the same points with the same residual block state.Benchmark
cpp/bench_mark/sprintz_batch_decode_benchmark.cc(built with-DBUILD_BENCHMARK=ON), Apple Silicon, Release, 2M values, batch capacity 129, best of 5. The baseline is the parent commit built in a separate worktree with identical CMake flags and the same benchmark source; there both arms run the old per-value code.Split by change: removing the per-block allocations alone gives 2.0-2.35x (per-value column vs before), and the batch loop adds a further 1.38-1.71x. Batch capacity 1024 was within noise of 129.
Reproduce:
Tests
40 new tests in
cpp/test/encoding/sprintz_codec_test.cc(theSprintzCodecTestsuite is now 56 tests) compare the batch overrides against the per-value loop they replace, for all four types, checking values bitwise, counts, stream position and residualhas_remaining()state:read_exactrecovering the full input;ByteStreampage size so block payload reads cross page boundaries;read_exact(chunks of 1, 8, 37 and 129).Cross-language validation on Java-generated bytes, since the parity tests above share the modified
decode_block()and cannot show on their own that the C++ decoder still reads what another implementation wrote. Six golden streams are embedded in the test, produced by the JavaIntSprintzEncoder/LongSprintzEncoder/FloatSprintzEncoder/DoubleSprintzEncoderwith their defaultfirepredictor:For each fixture the test first asserts that the C++ encoder emits byte-for-byte the same stream for the same values, then decodes the Java bytes through
read_exact(batch plus scalar handoff), a pure per-value drain, and a batch drain with capacities that split blocks at arbitrary points.Full C++ suite: 1583 passed, 0 failed, 3 environment-dependent skips.
./mvnw spotless:check -P with-java,with-cpppasses.Follow-ups (tracked as issues, not in this PR)
recalculate()(zigzag + FIRE/delta, eight scalar steps per block) is still scalar; measured at roughly 17-25% of batch decode time. Fusing or vectorising it is the next step.skip_exact_*for SPRINTZ still runs the per-value loop; onlyread_batch_*was optimised.decode_block()write out of bounds. Security hardening, deliberately kept out of this performance PR.