Skip to content

perf: reuse the inflate output buffer in the gzip/deflate decoders - #1509

Draft
pjfanning wants to merge 2 commits into
apache:mainfrom
pjfanning:perf-inflate-output-buffer
Draft

pjfanning wants to merge 2 commits into
apache:mainfrom
pjfanning:perf-inflate-output-buffer

Conversation

@pjfanning

@pjfanning pjfanning commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Motivation:
DeflateDecompressorBase.Inflate.parse, used by the gzip and deflate decoders on both the server (decodeRequest) and the client, allocated a new maxBytesPerChunk (64 KiB by default) array on every call, then copied the inflated bytes out of it with ByteString.fromArray. When the compressed input arrives in small elements, as it usually does off the network, each element inflates to a few KiB but still costs a 64 KiB array. This is candidate 3 in #1491.

Modification:

  • The Inflate step now owns a ByteStringOutputStream (both decoders create the step inside their stage logic, so it belongs to one stream). Each call reserves maxBytesPerChunk, inflates straight into the stream's array, gives back the unused tail and hands the result over with takeByteString. That copies a result filling at most half the array and keeps the array for the next call. A fuller result is handed over without copying, and a fresh array is allocated next time.
  • New ByteStringOutputStream.unreserve(length) gives back the unused tail of a reservation whose final size is only known after filling it in. The compressor side of Investigate wider use of ByteStringOutputStream and Pekko 2.0 ByteString APIs #1491 (candidate 1) needs the same thing for Deflater.deflate.
  • New DecoderBenchmark decodes 1 MiB of text as one element (text), the same compressed bytes in 1 KiB elements (text-1k), and 4 MiB of highly compressible data (repetitive).

Trade-off: an active decoding stream now keeps up to one maxBytesPerChunk buffer alive between elements, where before it was short-lived garbage. Decoder stages live only as long as an entity stream, and each Inflater already holds about 40 KB of native zlib state.

Result:
Allocation per decoded payload, from -prof gc (gc.alloc.rate.norm). gzip and deflate are within 0.1% of each other:

input before after
text (1 MiB, one element) 4.77 MB 3.71 MB (−22%)
text-1k (same bytes, 1 KiB elements) 21.16 MB 1.22 MB (−94%)
repetitive (4 MiB output) 8.57 MB 4.37 MB (−49%)

Throughput still needs measuring on a quiet machine. These runs had a load average of 10–30, so the ms/op scores aren't reliable, although they did improve in every case.

To reproduce:

sbt "http-bench-jmh/clean" "http-bench-jmh/Jmh/run -f 1 -wi 3 -i 5 -w 1 -r 1 -prof gc .*coding.DecoderBenchmark.*"

That's 6 parameter combinations, about 50–60 s of benchmarking plus the build. Run it on main for the baseline: the benchmark file can be copied over as is.

Tests:

  • http-tests/testOnly coding.* CodingDirectivesSpec: 214 passed. The new CoderSpec test, "keep emitted chunks intact while the decoder reuses its output buffer", keeps every output chunk until the end. It covers both the copy path and the hand-over path, and fails (for gzip and deflate) if an emitted chunk still shares a buffer that a later inflate writes into.
  • http-core/testOnly ByteStringOutputStreamSpec: 12 passed, including 3 new tests for unreserve
  • http-core/mimaReportBinaryIssues, http/mimaReportBinaryIssues: passed
  • DecoderBenchmark with -prof gc, as above

References:
Refs #1491

🤖 Generated with Claude Code

Motivation:
DeflateDecompressorBase.Inflate allocated a new maxBytesPerChunk
(64 KiB) array on every parse call and then copied the inflated bytes
out of it. When the compressed input arrives in small elements, each
element inflates to a few KiB but still costs a 64 KiB array.

Modification:
Keep the output buffer on the Inflate step. A result that fills at most
half of it is copied out and the buffer is reused; a fuller one is
handed over with ByteString.fromArrayUnsafe and a new buffer is
allocated on the next call. Add DecoderBenchmark.

Result:
Allocation per decoded payload (gzip, deflate is the same):
1 MiB text in one element 4.77 MB -> 3.71 MB, the same in 1 KiB
elements 21.16 MB -> 1.22 MB, 4 MiB repetitive data 8.57 MB -> 4.37 MB.

Tests:
- http-tests/testOnly coding.* CodingDirectivesSpec: 214 passed, with a
  new CoderSpec test that keeps every output chunk and checks none
  changed; it fails if a chunk shares the reused buffer
- http/mimaReportBinaryIssues: passed
- DecoderBenchmark -prof gc (-f 1 -wi 3 -i 5 -w 1 -r 1)

References:
Refs apache#1491
@pjfanning pjfanning added this to the 2.1.0 milestone Nov 18, 2026
Motivation:
The previous commit hand-wrote the same copy-or-hand-over policy that
ByteStringOutputStream.takeByteString already implements. The inflater
only reports how much it wrote afterwards, so a reserved range needs a
way to give back its unused tail. The compressors (apache#1491 candidate 1)
need the same thing.

Modification:
Add ByteStringOutputStream.unreserve, and have Inflate reserve
maxBytesPerChunk, inflate into the stream's array, give back the unused
part and hand the result over with takeByteString.

Result:
One hand-over policy instead of two. Allocation is unchanged
(DecoderBenchmark: 3.71 MB / 1.22 MB / 4.37 MB per op).

Tests:
- http-core/testOnly ByteStringOutputStreamSpec: 12 passed (3 new for
  unreserve)
- http-tests/testOnly coding.* CodingDirectivesSpec: 214 passed
- http-core/mimaReportBinaryIssues, http/mimaReportBinaryIssues: passed

References:
Refs apache#1491
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.

1 participant