aboutsummaryrefslogtreecommitdiff
path: root/src/liblzma/api/lzma
diff options
context:
space:
mode:
authorJia Tan <jiat0218@gmail.com>2023-05-09 20:20:06 +0800
committerJia Tan <jiat0218@gmail.com>2023-05-11 23:54:44 +0800
commit8f236574986e7c414c0ea059f441982d1387e6a4 (patch)
treea7f93f05e0905183658a452528c9d4bb9a4ebd81 /src/liblzma/api/lzma
parentliblzma: Creates IS_ENC_DICT_SIZE_VALID() macro. (diff)
downloadxz-8f236574986e7c414c0ea059f441982d1387e6a4.tar.xz
liblzma: Exports lzma_mt_block_size() as an API function.
The lzma_mt_block_size() was previously just an internal function for the multithreaded .xz encoder. It is used to provide a recommended Block size for a given filter chain. This function is helpful to determine the maximum Block size for the multithreaded .xz encoder when one wants to change the filters between blocks. Then, this determined Block size can be provided to lzma_stream_encoder_mt() in the lzma_mt options parameter when intializing the coder. This requires one to know all the filter chains they are using before starting to encode (or at least the filter chain that will need the largest Block size), but that isn't a bad limitation.
Diffstat (limited to '')
-rw-r--r--src/liblzma/api/lzma/container.h28
1 files changed, 28 insertions, 0 deletions
diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h
index 48a64365..7e4ca3bf 100644
--- a/src/liblzma/api/lzma/container.h
+++ b/src/liblzma/api/lzma/container.h
@@ -436,6 +436,34 @@ extern LZMA_API(lzma_ret) lzma_stream_encoder_mt(
/**
+ * \brief Calculate recommended Block size for multithreaded .xz encoder
+ *
+ * This calculates a recommended Block size for multithreaded encoding given
+ * a filter chain. This is used internally by lzma_stream_encoder_mt() to
+ * determine the Block size if the block_size member is not set to the
+ * special value of 0 in the lzma_mt options struct.
+ *
+ * If one wishes to change the filters between Blocks, this function is
+ * helpful to set the block_size member of the lzma_mt struct before calling
+ * lzma_stream_encoder_mt(). Since the block_size member represents the
+ * maximum possible Block size for the multithreaded .xz encoder, one can
+ * use this function to find the maximum recommended Block size based on
+ * all planned filter chains. Otherwise, the multithreaded encoder will
+ * base its maximum Block size on the first filter chain used (if the
+ * block_size member is not set), which may unnecessarily limit the Block
+ * size for a later filter chain.
+ *
+ * \param filters Array of filters terminated with
+ * .id == LZMA_VLI_UNKNOWN.
+ *
+ * \return Recommended Block size in bytes, or UINT64_MAX if
+ * an error occurred.
+ */
+extern LZMA_API(uint64_t) lzma_mt_block_size(const lzma_filter *filters)
+ lzma_nothrow;
+
+
+/**
* \brief Initialize .lzma encoder (legacy file format)
*
* The .lzma format is sometimes called the LZMA_Alone format, which is the