Struct xz::stream::MtStreamBuilder

pub struct MtStreamBuilder { /* fields omitted */ }

Builder to create a multi-threaded stream encoder.

Implementations

impl MtStreamBuilder

pub fn new() -> MtStreamBuilder

Creates a new blank builder to create a multithreaded encoding Stream.

pub fn threads(&mut self, threads: u32) -> &mut MtStreamBuilder

Configures the number of worker threads to use

pub fn block_size(&mut self, block_size: u64) -> &mut MtStreamBuilder

Configures the maximum uncompressed size of a block

The encoder will start a new .xz block every block_size bytes. Using FullFlush or FullBarrier with process the caller may tell liblzma to start a new block earlier.

With LZMA2, a recommended block size is 2-4 times the LZMA2 dictionary size. With very small dictionaries, it is recommended to use at least 1 MiB block size for good compression ratio, even if this is more than four times the dictionary size. Note that these are only recommendations for typical use cases; feel free to use other values. Just keep in mind that using a block size less than the LZMA2 dictionary size is waste of RAM.

Set this to 0 to let liblzma choose the block size depending on the compression options. For LZMA2 it will be 3*dict_size or 1 MiB, whichever is more.

For each thread, about 3 * block_size bytes of memory will be allocated. This may change in later liblzma versions. If so, the memory usage will probably be reduced, not increased.

pub fn timeout_ms(&mut self, timeout: u32) -> &mut MtStreamBuilder

Timeout to allow process to return early

Multithreading can make liblzma to consume input and produce output in a very bursty way: it may first read a lot of input to fill internal buffers, then no input or output occurs for a while.

In single-threaded mode, process won't return until it has either consumed all the input or filled the output buffer. If this is done in multithreaded mode, it may cause a call process to take even tens of seconds, which isn't acceptable in all applications.

To avoid very long blocking times in process, a timeout (in milliseconds) may be set here. If process would block longer than this number of milliseconds, it will return with Ok`. Reasonable values are 100 ms or more. The xz command line tool uses 300 ms.

If long blocking times are fine for you, set timeout to a special value of 0, which will disable the timeout mechanism and will make process block until all the input is consumed or the output buffer has been filled.

pub fn preset(&mut self, preset: u32) -> &mut MtStreamBuilder

Compression preset (level and possible flags)

The preset is set just like with Stream::new_easy_encoder. The preset is ignored if filters below have been specified.

pub fn filters(&mut self, filters: Filters) -> &mut MtStreamBuilder

Configure a custom filter chain

pub fn check(&mut self, check: Check) -> &mut MtStreamBuilder

Configures the integrity check type

pub fn memusage(&self) -> u64

Calculate approximate memory usage of multithreaded .xz encoder

pub fn encoder(&self) -> Result<Stream, Error>

Initialize multithreaded .xz stream encoder.