Struct xz2::stream::MtStreamBuilder

source · [−]

pub struct MtStreamBuilder { /* private fields */ }

Expand description

Builder to create a multi-threaded stream encoder.

Implementations

source

impl MtStreamBuilder

source

pub fn new() -> MtStreamBuilder

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

source

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

Configures the number of worker threads to use

source

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

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.

source

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

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.

source