Compressing Frames

For compressing stream payloads in-line, Rogue provides rogue.utilities.StreamZip. It consumes ordinary Rogue frames, compresses the payload bytes with bzip2, and forwards a new frame downstream while preserving frame metadata.

Use StreamZip when the next stage in the graph expects compressed payloads, such as a file writer or a remote receiver that will later use StreamUnZip.

Compression Pipeline

A common compression chain looks like this:

  • Prbs generates deterministic test payloads.

  • StreamZip compresses each frame payload.

  • StreamWriter records the compressed frames for later replay or analysis.

Python Example

import rogue.utilities as ru
import rogue.utilities.fileio as ruf

# Capture compressed output to file.
writer = ruf.StreamWriter()
writer.setBufferSize(1000)
writer.setMaxSize(1_000_000)

# Source generator and compression stage.
prbs = ru.Prbs()
comp = ru.StreamZip()

# Pipeline: PRBS source -> compressor -> file sink.
prbs >> comp >> writer.getChannel(0)

# Generate and capture compressed traffic.
writer.open('test.dat')
for _ in range(1000):
    prbs.genFrame(1000)
writer.close()

C++ Example

#include <rogue/utilities/Prbs.h>
#include <rogue/utilities/StreamZip.h>
#include <rogue/utilities/fileio/StreamWriter.h>
#include <rogue/utilities/fileio/StreamWriterChannel.h>

namespace ru  = rogue::utilities;
namespace ruf = rogue::utilities::fileio;

int main() {
    // Capture compressed output to file.
    auto writer = ruf::StreamWriter::create();
    writer->setBufferSize(10000);
    writer->setMaxSize(100000000);
    writer->setDropErrors(true);

    // Source generator and compression stage.
    auto prbs = ru::Prbs::create();
    auto comp = ru::StreamZip::create();

    // Pipeline: PRBS source -> compressor -> file sink.
    *prbs >> comp >> writer->getChannel(0);

    // Generate and capture compressed traffic.
    writer->open("test.dat");
    for (int i = 0; i < 1000; ++i) prbs->genFrame(1000);
    writer->close();
    return 0;
}

Threading And Lifecycle

StreamZip does not create an internal worker thread. Compression runs inside acceptFrame() in the caller thread, and the implementation locks the input frame while reading payload bytes.

Operational Notes

  • Output frame allocation starts from the input payload size and grows if needed.

  • Frame metadata is preserved across the compression step.

  • Compression is easiest to reason about when the corresponding replay or receive path clearly includes Decompressing Frames.

API Reference