Skip to content

perf(cpp): batch decode for the SPRINTZ codec - #1110

Merged
ColinLeeo merged 2 commits into
developfrom
colin/sprintz-batch-decode-62fcee
Nov 16, 2026
Merged

ColinLeeo merged 2 commits into
developfrom
colin/sprintz-batch-decode-62fcee

Conversation

@ColinLeeo

@ColinLeeo ColinLeeo commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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_double 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 therefore cost 129 virtual calls.

Changes

  • cpp/src/encoding/sprintz_decoder.h: new protected SprintzDecoder::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.
  • The four concrete decoders override read_batch_int32/int64/float/double on 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 with set_width() instead of std::make_shared per 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/DoubleSprintzDecoder no longer shadow the base class's current_count_/decode_size_/is_block_read_ members.
  • The SIMD unpack path is untouched; the packers still dispatch to native AVX2 at runtime.

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 while current_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 scalar read_one fallback. FloatSprintzDecoder/DoubleSprintzDecoder compare against decode_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.

type pattern values/s before after, per-value after, batch overall
INT32 smooth 107M 220M 330M 3.1x
INT32 entropy 93M 189M 261M 2.8x
INT32 constant 114M 251M 407M 3.6x
INT64 smooth 108M 240M 381M 3.5x
INT64 entropy 99M 234M 364M 3.7x
INT64 constant 118M 268M 458M 3.9x
FLOAT smooth 105M 233M 338M 3.2x
FLOAT entropy 107M 231M 335M 3.1x
FLOAT constant 117M 255M 391M 3.3x
DOUBLE smooth 105M 220M 329M 3.1x
DOUBLE entropy 105M 216M 317M 3.0x
DOUBLE constant 121M 267M 425M 3.5x

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:

cmake -S cpp -B cpp/target/build -DCMAKE_BUILD_TYPE=Release -DBUILD_BENCHMARK=ON
cmake --build cpp/target/build --target sprintz_batch_decode_benchmark
./cpp/target/build/sprintz_batch_decode_benchmark 2000000 5 129

Tests

40 new tests in cpp/test/encoding/sprintz_codec_test.cc (the SprintzCodecTest suite 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 residual has_remaining() state:

  • smooth, high-entropy, constant and jump streams;
  • a capacity script crossing block boundaries (1, 2, 3, 5, 7, 8, 9, 10, 17, 129) and pseudo-random capacities that split blocks at arbitrary points;
  • every value count 0..40 around block boundaries, plus read_exact recovering the full input;
  • zero and negative capacity, end of stream, repeated calls after draining;
  • every truncated prefix of a stream (same return codes, same values, same stop point);
  • a 16-byte ByteStream page size so block payload reads cross page boundaries;
  • chunked 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 Java IntSprintzEncoder/LongSprintzEncoder/FloatSprintzEncoder/DoubleSprintzEncoder with their default fire predictor:

  • INT32: one full block plus a short tail block (13 values), a constant run (12), and a stream that crosses the encoder's 16-group flush and ends in a short block (140);
  • INT64: epoch-millisecond timestamps (17);
  • FLOAT and DOUBLE: smooth series (12 and 25). Expected values for these are built by reinterpreting Java's raw bit patterns, so the comparison is bit-exact.

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-cpp passes.

Follow-ups (tracked as issues, not in this PR)

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

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

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.
@ColinLeeo

Copy link
Copy Markdown
Contributor Author

Added cross-language validation for the concern that the scalar/batch parity tests share the modified decode_block() and therefore cannot establish compatibility on their own. Six golden SPRINTZ streams produced by the Java encoders (IntSprintzEncoder, LongSprintzEncoder, FloatSprintzEncoder, DoubleSprintzEncoder, default fire predictor) are now embedded in cpp/test/encoding/sprintz_codec_test.cc: a full block with a short tail, a constant run, a stream crossing the encoder's 16-group flush, INT64 timestamps, and smooth FLOAT/DOUBLE series. For each one the test asserts the C++ encoder emits the same bytes 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; FLOAT/DOUBLE expectations are built from Java's raw bit patterns so the comparison is bit-exact. Full C++ suite now 1583 passed, 0 failed, 3 environment-dependent skips; spotless passes.

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.90%. Comparing base (4ef3102) to head (3c6c5ac).
⚠️ Report is 1 commits behind head on develop.

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

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.

3 participants