how to use brotli::BrotliCompressor, the correct/intended way? #105

New Issue

claunia · 2026-01-29T20:34:56Z

claunia commented

2026-01-29 20:34:56 +00:00

Originally created by @nitram509 on GitHub (May 16, 2016).

Abstract

I appreciate that the brotli library offers a class for stream based compression.
In order to use this class as intended, I have some questions, which the sparse header file didn't answer.

I consider myself as a novice C-Programmer and I'm just following the concept of
don't make me think - applied to API design ;-)

General usage

Just from looking at the public method's signatures, I have some expectations.
I would use the BrotliCompression class like this (pseudo-code).

c = new BrotliCompressor(params);
partialBuffer = new buffer(c->input_block_size())    // use max partial buffer size for stream
for partialBuffer in hugeInputBuffer {
    c->CopyInputToRingBuffer(partialBuffer)
    c->WriteBrotliData(isLast=false, doFlush=false, size(partialBuffer), &outputBuffer)
}
c->WriteBrotliData(isLast=true, doFlush=true, 0, &outputBuffer)  // final flush

I wouldn't expect doing anything more, to write a valid brotli stream, which I can send over wire or save to disk.

Questions

Why are the following methods public, and when to use them?
- WriteMetaBlock()
- WriteMetadata()
- FinishStream
- BrotliSetCustomDictionary()
- WriteStreamHeader()
I didn't use them and the compressor works fine (no errors)
- IMHO, If they are mandatory, the compressor should fail fast

Is_Last vs. Do_Flush vs. FinishStream()

I know, when it comes to file IO, what flush() means. But with these three options I'm confused.

Questions

When do I use what?
What are the consequences?
What does Is_Last do?
- What is the consequence of not doing it?
- Is this mandatory or just a hint?
When there is a FinishStream(),
- Why isn't there a StartStream()? (it's all about wording, e.g. have consistent and symmetric naming)

I'm looking forward to a fruitful discussion :-)

Thanks in advance
Martin

Originally created by @nitram509 on GitHub (May 16, 2016). ### Abstract I appreciate that the brotli library offers a class for stream based compression. In order to use this class as intended, I have some questions, which the sparse header file didn't answer. I consider myself as a novice C-Programmer and I'm just following the concept of [don't make me think](https://www.sensible.com/dmmt.html) - applied to API design ;-) ### General usage Just from looking at the public method's signatures, I have some expectations. I would use the BrotliCompression class like this (pseudo-code). ``` c = new BrotliCompressor(params); partialBuffer = new buffer(c->input_block_size()) // use max partial buffer size for stream for partialBuffer in hugeInputBuffer { c->CopyInputToRingBuffer(partialBuffer) c->WriteBrotliData(isLast=false, doFlush=false, size(partialBuffer), &outputBuffer) } c->WriteBrotliData(isLast=true, doFlush=true, 0, &outputBuffer) // final flush ``` I wouldn't expect doing anything more, to write a valid brotli stream, which I can send over wire or save to disk. ##### Questions - Why are the following methods public, and when to use them? - WriteMetaBlock() - WriteMetadata() - FinishStream - BrotliSetCustomDictionary() - WriteStreamHeader() - I didn't use them and the compressor works fine (no errors) - IMHO, If they are mandatory, the compressor should [fail fast](https://en.wikipedia.org/wiki/Fail-fast) ### Is_Last vs. Do_Flush vs. FinishStream() I know, when it comes to file IO, what flush() means. But with these three options I'm confused. ##### Questions - When do I use what? - What are the consequences? - What does Is_Last do? - What is the consequence of not doing it? - Is this mandatory or just a hint? - When there is a FinishStream(), - Why isn't there a StartStream()? (it's all about wording, e.g. have consistent and symmetric naming) I'm looking forward to a fruitful discussion :-) Thanks in advance Martin

claunia referenced this issue

2026-01-29 20:50:28 +00:00

[PR #105] [MERGED] [python] expose new encoder parameters as kwargs of brotli.compress #709

claunia referenced this issue

2026-01-29 20:50:29 +00:00

[PR #105] [python] expose new encoder parameters as kwargs of brotli.compress #713

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/brotli#105