change advanced parameter name: ZSTD_c_repcodeResolution

and updated its documentation.
Note: older name ZSTD_c_searchForExternalRepcodes remains supported via #define

diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c
index 6b3efb33630ee56b2f8d533e6237a7ca09a0a4c8..be6107cb8e136b11c13770be63534f60e00f5638 100644 (file)
--- a/lib/compress/zstd_compress.c
+++ b/lib/compress/zstd_compress.c
@@ -634,7 +634,7 @@ ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter param)
         bounds.upperBound = ZSTD_BLOCKSIZE_MAX;
         return bounds;
 
-    case ZSTD_c_searchForExternalRepcodes:
+    case ZSTD_c_repcodeResolution:
         bounds.lowerBound = (int)ZSTD_ps_auto;
         bounds.upperBound = (int)ZSTD_ps_disable;
         return bounds;
@@ -708,7 +708,7 @@ static int ZSTD_isUpdateAuthorized(ZSTD_cParameter param)
     case ZSTD_c_prefetchCDictTables:
     case ZSTD_c_enableSeqProducerFallback:
     case ZSTD_c_maxBlockSize:
-    case ZSTD_c_searchForExternalRepcodes:
+    case ZSTD_c_repcodeResolution:
     default:
         return 0;
     }
@@ -768,7 +768,7 @@ size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value)
     case ZSTD_c_prefetchCDictTables:
     case ZSTD_c_enableSeqProducerFallback:
     case ZSTD_c_maxBlockSize:
-    case ZSTD_c_searchForExternalRepcodes:
+    case ZSTD_c_repcodeResolution:
         break;
 
     default: RETURN_ERROR(parameter_unsupported, "unknown parameter");
@@ -1020,8 +1020,8 @@ size_t ZSTD_CCtxParams_setParameter(ZSTD_CCtx_params* CCtxParams,
         CCtxParams->maxBlockSize = (size_t)value;
         return CCtxParams->maxBlockSize;
 
-    case ZSTD_c_searchForExternalRepcodes:
-        BOUNDCHECK(ZSTD_c_searchForExternalRepcodes, value);
+    case ZSTD_c_repcodeResolution:
+        BOUNDCHECK(ZSTD_c_repcodeResolution, value);
         CCtxParams->searchForExternalRepcodes = (ZSTD_ParamSwitch_e)value;
         return CCtxParams->searchForExternalRepcodes;
 
@@ -1169,7 +1169,7 @@ size_t ZSTD_CCtxParams_getParameter(
     case ZSTD_c_maxBlockSize:
         *value = (int)CCtxParams->maxBlockSize;
         break;
-    case ZSTD_c_searchForExternalRepcodes:
+    case ZSTD_c_repcodeResolution:
         *value = (int)CCtxParams->searchForExternalRepcodes;
         break;
     default: RETURN_ERROR(parameter_unsupported, "unknown parameter");

diff --git a/lib/zstd.h b/lib/zstd.h
index 7f1d8c4832369ff32376f37132c0f5e0fac255b0..ffcb059cf8da7b80216801c1ab5b1fcbbb2048e6 100644 (file)
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -1637,6 +1637,12 @@ ZSTDLIB_STATIC_API size_t ZSTD_mergeBlockDelimiters(ZSTD_Sequence* sequences, si
  *    If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain
  *    valid block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
  *
+ *    When ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, it's possible to decide generating repcodes
+ *    using the advanced parameter ZSTD_c_repcodeResolution. Repcodes will improve compression ratio, though the benefit
+ *    can vary greatly depending on Sequences. On the other hand, repcode resolution is an expensive operation.
+ *    By default, it's disabled at low (<10) compression levels, and enabled above the threshold (>=10).
+ *    ZSTD_c_repcodeResolution makes it possible to directly manage this processing in either direction.
+ *
  *    If ZSTD_c_validateSequences == 0, this function blindly accepts the Sequences provided. Invalid Sequences cause undefined
  *    behavior. If ZSTD_c_validateSequences == 1, then the function will detect invalid Sequences (see doc/zstd_compression_format.md for
  *    specifics regarding offset/matchlength requirements) and then bail out and return an error.
@@ -2301,18 +2307,18 @@ ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const vo
  */
 #define ZSTD_c_maxBlockSize ZSTD_c_experimentalParam18
 
-/* ZSTD_c_searchForExternalRepcodes
- * Note: for now, this param only has an effect if ZSTD_c_blockDelimiters is
- * set to ZSTD_sf_explicitBlockDelimiters. That may change in the future.
+/* ZSTD_c_repcodeResolution
+ * This parameter only has an effect if ZSTD_c_blockDelimiters is
+ * set to ZSTD_sf_explicitBlockDelimiters (may change in the future).
  *
- * This parameter affects how zstd parses external sequences, such as sequences
- * provided through compressSequences() and variant API
+ * This parameter affects how zstd parses external sequences,
+ * provided via the ZSTD_compressSequences*() API
  * or from an external block-level sequence producer.
  *
- * If set to ZSTD_ps_enable, the library will check for repeated offsets in
+ * If set to ZSTD_ps_enable, the library will check for repeated offsets within
  * external sequences, even if those repcodes are not explicitly indicated in
  * the "rep" field. Note that this is the only way to exploit repcode matches
- * while using compressSequences() or an external sequence producer, since zstd
+ * while using compressSequences*() or an external sequence producer, since zstd
  * currently ignores the "rep" field of external sequences.
  *
  * If set to ZSTD_ps_disable, the library will not exploit repeated offsets in
@@ -2323,7 +2329,8 @@ ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const vo
  * The default value is ZSTD_ps_auto, for which the library will enable/disable
  * based on compression level (currently: level<10 disables, level>=10 enables).
  */
-#define ZSTD_c_searchForExternalRepcodes ZSTD_c_experimentalParam19
+#define ZSTD_c_repcodeResolution ZSTD_c_experimentalParam19
+#define ZSTD_c_searchForExternalRepcodes ZSTD_c_experimentalParam19 /* older name */
 
 
 /*! ZSTD_CCtx_getParameter() :

diff --git a/tests/fullbench.c b/tests/fullbench.c
index 09c42615482fe9007925b6af2ccceebc8d0b75ea..320b0ed73724e86634a9129b2c2d525a13d9facd 100644 (file)
--- a/tests/fullbench.c
+++ b/tests/fullbench.c
@@ -618,7 +618,7 @@ local_compressSequencesAndLiterals(const void* input, size_t inputSize,
     ZSTD_CCtx_reset(g_zcc, ZSTD_reset_session_and_parameters);
     ZSTD_CCtx_setParameter(g_zcc, ZSTD_c_blockDelimiters, ZSTD_sf_explicitBlockDelimiters);
 # if 0 /* for tests */
-    ZSTD_CCtx_setParameter(g_zcc, ZSTD_c_searchForExternalRepcodes, ZSTD_ps_enable);
+    ZSTD_CCtx_setParameter(g_zcc, ZSTD_c_repcodeResolution, ZSTD_ps_enable);
 #endif
     assert(8 + nbSeqs * sizeof(ZSTD_Sequence) + nbLiterals == inputSize); (void)inputSize;
     (void)payload;

diff --git a/tests/fuzz/zstd_helpers.c b/tests/fuzz/zstd_helpers.c
index c89e448d0711f171437775eb6da2427534e901d0..f3b2e6fba4c88bee7646bfb3d6693638205f46ad 100644 (file)
--- a/tests/fuzz/zstd_helpers.c
+++ b/tests/fuzz/zstd_helpers.c
@@ -146,7 +146,7 @@ void FUZZ_setRandomParameters(ZSTD_CCtx *cctx, size_t srcSize, FUZZ_dataProducer
     setRand(cctx, ZSTD_c_prefetchCDictTables, 0, 2, producer);
     setRand(cctx, ZSTD_c_maxBlockSize, ZSTD_BLOCKSIZE_MAX_MIN, ZSTD_BLOCKSIZE_MAX, producer);
     setRand(cctx, ZSTD_c_validateSequences, 0, 1, producer);
-    setRand(cctx, ZSTD_c_searchForExternalRepcodes, 0, 2, producer);
+    setRand(cctx, ZSTD_c_repcodeResolution, 0, 2, producer);
     if (FUZZ_dataProducer_uint32Range(producer, 0, 1) == 0) {
       setRand(cctx, ZSTD_c_srcSizeHint, ZSTD_SRCSIZEHINT_MIN, 2 * srcSize, producer);
     }