fix(parquet/encoding): read ahead in the streaming value buffer

[joechenrh]

Summary

The streaming value buffer's Fill read only need bytes per call, so the decoders call Fill(Read) per value. And each call just copies a few bytes out of an already-decoded block. This makes streaming decoding 1.2–1.9× slower than the materialized path for small values.

Now Fill reads toward the end of the current chunk — so the reader is called once per chunk. And Recycle moves the unconsumed data to the front once the consumed data exceeds half the buffer, instead of allocating a fresh chunk on rotate.

Correction

I need to correct — and apologize for — something I wrote while landing the streaming decode in #880:

I prototyped a read-ahead buffer to close the zstd gap and measured ≈0 improvement (the cost is the extra copy, not the read count), so I dropped it.

That conclusion was wrong, and worse, it reverted something that had already been working. An earlier iteration of the value buffer did read ahead correctly; but dropped in the later refactor. The re-prototype behind the "≈0 improvement" claim was then broken. From testing, this adds a 1.2–1.9× small-value decode regression for zstd.

Sorry for removing the code that works and then drawing the wrong conclusion. This PR restores read-ahead with some changes and adds a test for that path.

Results

Decode-only, ReadBatchInPage; single ByteArray column, 32 MiB pages, arrow-go's default BufferSize (16 KiB), median of 3.

Ratio = materialized / streaming, so >1 means streaming is slower:

value size	zstd before	zstd after	gzip before	gzip after
9 B	1.85×	1.16×	1.78×	1.33×
33 B	1.66×	1.15×	1.58×	1.43×
129 B	1.23×	1.04×	0.91×	0.65×

ReadBatch gives almost the same ratios.

The remaining ~1.04–1.16× (zstd) is the streaming path's inherent overhead: the codec pulls its compressed input incrementally, so it issues many more reads than the materialized path's single bulk read — profiling attributes most of the gap to those read syscalls — plus a Fill/Advance call per value. Read-ahead removes what the value-side read count added; it does not remove those.

gzip

gzip benefits too, but its residual is higher (~1.33× at 9 B vs zstd's ~1.16×). The extra gap is in flate's input reading. Both paths read the compressed input byte by byte; the difference is inlining:

• The materialized path gives flate a *bytes.Reader, whose ReadByte inlines, so flate keeps its bit-buffer state in registers across the read loop (huffmanBytesReader).
• Streaming gives flate a plain reader, so ReadByte is a real call per byte and the state spills around each call (huffmanBufioReader) — ~1.85× slower in that loop.

Feeding flate a *bytes.Reader under streaming recovers it (~1.06×), but that means holding the whole compressed page in memory, which gives up the streaming memory bound.

[zeroshade]

Read-ahead/refill logic looks correct — region clamping, alias stability across rotate, and short/EOF handling all check out. One doc-accuracy nit inline.

[zeroshade]

nit: peak = one chunk is a little stronger than what the code guarantees. Compaction only runs once the consumed prefix passes half the chunk, so a small consumed prefix followed by a larger value can still fall through to rotate, which keeps the old chunk in live while allocating the new one — a transient two-chunk peak. Suggest softening to something like keeps read-ahead room and makes rotations rare rather than implying a hard one-chunk ceiling.

[joechenrh]

Updated in joechenrh@80b7fe3 . Reworded the comment to describe the compaction/rotation tradeoff without implying a hard one-chunk ceiling. Thanks for catching that!