From: W. Felix Handte <w@felixhandte.com>
Date: Wed, 13 Mar 2024 20:56:54 +0000 (-0400)
Subject: Promote `ZSTD_c_targetCBlockSize` Parameter to Stable API
X-Git-Tag: v1.5.6^2~19^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F3964%2Fhead;p=thirdparty%2Fzstd.git

Promote `ZSTD_c_targetCBlockSize` Parameter to Stable API

This feature has demonstrated itself to be useful in web compression and we
want to encourage other folks to use it. But we currently make it difficult
to do so since it's locked away in the experimental API.

The API itself is really straightforward and I think it's fine to commit to
maintaining support / compatibility for this API even if in the future the
underlying implementation may continue to evolve.

Note that this commit changes its enum name and also its numeric value. Users
who respected the instructions of using the experimental API should be fine
with both of these changes since they should only have referred to it by the.

Conceivably someone could have done bad feature detection of this capability
by doing `#ifdef ZSTD_c_targetCBlockSize` which will now return false since
it's no longer a macro... but I think that's an acceptable hypothetical
breakage.
---

diff --git a/lib/zstd.h b/lib/zstd.h
index 841269305..d2621c5c9 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -390,6 +390,16 @@ typedef enum {
                               * The higher the value of selected strategy, the more complex it is,
                               * resulting in stronger and slower compression.
                               * Special: value 0 means "use default strategy". */
+    ZSTD_c_targetCBlockSize=130, /* Tries to fit compressed block size to be
+                                  * around targetCBlockSize. No target when
+                                  * targetCBlockSize == 0. There is no guarantee
+                                  * on compressed block size (default:0).
+                                  * Since the decoder has to buffer a complete
+                                  * block to begin decoding it, in low band-
+                                  * width streaming environments this may
+                                  * improve end-to-end latency. Bound by
+                                  * ZSTD_TARGETCBLOCKSIZE_MIN and
+                                  * ZSTD_TARGETCBLOCKSIZE_MAX. */
     /* LDM mode parameters */
     ZSTD_c_enableLongDistanceMatching=160, /* Enable long distance matching.
                                      * This parameter is designed to improve compression ratio
@@ -469,7 +479,6 @@ typedef enum {
      * ZSTD_c_forceMaxWindow
      * ZSTD_c_forceAttachDict
      * ZSTD_c_literalCompressionMode
-     * ZSTD_c_targetCBlockSize
      * ZSTD_c_srcSizeHint
      * ZSTD_c_enableDedicatedDictSearch
      * ZSTD_c_stableInBuffer
@@ -490,7 +499,7 @@ typedef enum {
      ZSTD_c_experimentalParam3=1000,
      ZSTD_c_experimentalParam4=1001,
      ZSTD_c_experimentalParam5=1002,
-     ZSTD_c_experimentalParam6=1003,
+     /* was ZSTD_c_experimentalParam6=1003; is now ZSTD_c_targetCBlockSize */
      ZSTD_c_experimentalParam7=1004,
      ZSTD_c_experimentalParam8=1005,
      ZSTD_c_experimentalParam9=1006,
@@ -1951,11 +1960,6 @@ ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const vo
  */
 #define ZSTD_c_literalCompressionMode ZSTD_c_experimentalParam5
 
-/* Tries to fit compressed block size to be around targetCBlockSize.
- * No target when targetCBlockSize == 0.
- * There is no guarantee on compressed block size (default:0) */
-#define ZSTD_c_targetCBlockSize ZSTD_c_experimentalParam6
-
 /* User's best guess of source size.
  * Hint is not valid when srcSizeHint == 0.
  * There is no guarantee that hint is close to actual source size,