Merge pull request #234 from Nullus157/new/feat

Add new feature `zstdmt` for `zstd::CParameter::nb_workers`

Author: NobodyXu

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0),
 
 ## Unreleased
 
+- Add `zstdmt` crate feature that enables `zstd-safe/zstdmt`, allowing multi-threaded functionality to work as expected.
+
 ## 0.4.0 - 2023-05-10
 
 - `Level::Precise` variant now takes a `i32` instead of `u32`.

Cargo.toml

@@ -28,6 +28,7 @@ lzma = ["xz2"]
 xz = ["xz2"]
 zlib = ["flate2"]
 zstd = ["libzstd", "zstd-safe"]
+zstdmt = ["zstd", "zstd-safe/zstdmt"]
 
 [dependencies]
 brotli = { version = "3.3", optional = true, default-features = false, features = ["std"] }

src/lib.rs

@@ -121,7 +121,7 @@
 )]
 //!
 
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
 #![warn(
     missing_docs,
     rust_2018_idioms,
@@ -326,6 +326,14 @@ pub mod zstd {
         ///
         /// If set to 0, compression functions will block; if set to 1 or more, compression will
         /// run in background threads and `flush` pushes bytes through the compressor.
+        ///
+        /// # Panics
+        ///
+        /// This parameter requires feature `zstdmt` to be enabled, otherwise it will cause a panic
+        /// when used in `ZstdEncoder::with_quality_and_params()` calls.
+        //
+        // TODO: make this a normal feature guarded fn on next breaking release
+        #[cfg_attr(docsrs, doc(cfg(feature = "zstdmt")))]
         pub fn nb_workers(value: u32) -> Self {
             Self(NbWorkers(value))
         }

src/macros.rs

@@ -88,6 +88,16 @@ macro_rules! algos {
 
             /// Creates a new encoder, using the specified compression level and parameters, which
             /// will read uncompressed data from the given stream and emit a compressed stream.
+            ///
+            /// # Panics
+            ///
+            /// Panics if this function is called with a [`CParameter::nb_workers()`] parameter and
+            /// the `zstdmt` crate feature is _not_ enabled.
+            ///
+            /// [`CParameter::nb_workers()`]: crate::zstd::CParameter
+            //
+            // TODO: remove panic note on next breaking release, along with `CParameter::nb_workers`
+            // change
             pub fn with_quality_and_params(inner: $inner, level: crate::Level, params: &[crate::zstd::CParameter]) -> Self {
                 Self {
                     inner: crate::$($mod::)+generic::Encoder::new(