zxc_pstream.h File Reference

Push-based, single-threaded streaming compression and decompression. More...

#include <stddef.h>
#include <stdint.h>
#include "zxc_export.h"
#include "zxc_opts.h"

Go to the source code of this file.

Data Structures
struct	zxc_inbuf_t
	Input buffer descriptor for push streaming. More...
struct	zxc_outbuf_t
	Output buffer descriptor for push streaming. More...

Typedefs
typedef struct zxc_cstream_s	zxc_cstream
	Opaque push-model compression stream (see zxc_cstream_create).
typedef struct zxc_dstream_s	zxc_dstream
	Opaque push-model decompression stream (see zxc_dstream_create).

Functions
zxc_cstream *	zxc_cstream_create (const zxc_compress_opts_t *opts)
	Creates a push compression stream.
void	zxc_cstream_free (zxc_cstream *cs)
	Releases a compression stream and all internal buffers.
int64_t	zxc_cstream_compress (zxc_cstream *cs, zxc_outbuf_t *out, zxc_inbuf_t *in)
	Pushes input bytes into the stream and drains compressed output.
int64_t	zxc_cstream_end (zxc_cstream *cs, zxc_outbuf_t *out)
	Finalises the stream: flushes pending data, writes EOF block + footer.
size_t	zxc_cstream_in_size (const zxc_cstream *cs)
	Suggested input chunk size for best throughput.
size_t	zxc_cstream_out_size (const zxc_cstream *cs)
	Suggested output chunk size that never triggers a partial drain.
zxc_dstream *	zxc_dstream_create (const zxc_decompress_opts_t *opts)
	Creates a push decompression stream.
void	zxc_dstream_free (zxc_dstream *ds)
	Releases a decompression stream.
int64_t	zxc_dstream_decompress (zxc_dstream *ds, zxc_outbuf_t *out, zxc_inbuf_t *in)
	Pushes compressed input and drains decompressed output.
int	zxc_dstream_finished (const zxc_dstream *ds)
	Reports whether the decoder has fully consumed a valid stream.
size_t	zxc_dstream_in_size (const zxc_dstream *ds)
	Suggested input chunk size for the decompressor.
size_t	zxc_dstream_out_size (const zxc_dstream *ds)
	Suggested output chunk size for the decompressor.

Detailed Description

Push-based, single-threaded streaming compression and decompression.

The counterpart of the FILE*-based zxc_stream_compress / zxc_stream_decompress. Those own the pipeline (read until EOF, write until done); here the caller stays in control: feed input chunks when they arrive, drain output chunks when ready, finalise on demand. Nothing blocks.

That is what you want inside a callback-driven library, an asynchronous event loop, a non-seeking network protocol (HTTP chunked transfer, gRPC, your own binary protocol), or any pipeline with no FILE* to block on.

One context, one thread at a time. To compress a single file end-to-end across threads, use zxc_stream_compress instead.

Compression usage

zxc_compress_opts_t opts = { .level = 3, .checksum_enabled = 1 };
zxc_cstream* cs = zxc_cstream_create(&opts);
 
uint8_t in_buf[64*1024], out_buf[64*1024];
zxc_outbuf_t out = { out_buf, sizeof out_buf, 0 };
 
ssize_t n;
while ((n = read_some(in_buf, sizeof in_buf)) > 0) {
    zxc_inbuf_t in = { in_buf, (size_t)n, 0 };
    while (in.pos < in.size) {
        int64_t r = zxc_cstream_compress(cs, &out, &in);
        if (r < 0) goto fatal;
        if (out.pos > 0) { write_to_sink(out_buf, out.pos); out.pos = 0; }
    }
}
 
int64_t pending;
do {
    pending = zxc_cstream_end(cs, &out);
    if (pending < 0) goto fatal;
    if (out.pos > 0) { write_to_sink(out_buf, out.pos); out.pos = 0; }
} while (pending > 0);
 
zxc_cstream_free(cs);

See also

zxc_stream.h for the multi-threaded FILE*-based pipeline.

zxc_buffer.h for one-shot in-memory compression.

Definition in file zxc_pstream.h.