From: Stella Lau <laus@fb.com>
Date: Mon, 21 Aug 2017 20:18:00 +0000 (-0700)
Subject: Add documentation for CCtx_params
X-Git-Tag: fuzz-corpora2~29^2^2~31
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1c0dbe81b17addc1f48be895326124158ea5a2c3;p=thirdparty%2Fzstd.git

Add documentation for CCtx_params
---

diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c
index b6774e947..c37b2ad49 100644
--- a/lib/compress/zstd_compress.c
+++ b/lib/compress/zstd_compress.c
@@ -471,12 +471,12 @@ size_t ZSTD_CCtxParam_setParameter(
         return 0;
 
     case ZSTD_p_jobSize :
-        if (params->nbThreads <= 1) { return ERROR(parameter_unsupported); }
+        if (params->nbThreads <= 1) return ERROR(parameter_unsupported);
         params->jobSize = value;
         return 0;
 
     case ZSTD_p_overlapSizeLog :
-        if (params->nbThreads <= 1) { return ERROR(parameter_unsupported); }
+        if (params->nbThreads <= 1) return ERROR(parameter_unsupported);
         params->overlapSizeLog = value;
         return 0;
 
@@ -526,6 +526,10 @@ size_t ZSTD_CCtx_applyCCtxParams(ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params
     if (params == NULL) { return ERROR(GENERIC); }
     if (cctx->cdict) { return ERROR(stage_wrong); }
 
+    /* TODO: some parameters can be set even if cctx->cdict.
+     * They can be set directly using ZSTD_CCtx_setParameter?
+     */
+
     /* Assume the compression and frame parameters are validated */
     cctx->requestedParams.cParams = params->cParams;
     cctx->requestedParams.fParams = params->fParams;
diff --git a/lib/zstd.h b/lib/zstd.h
index 0fd97cd6f..09b89911f 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -613,13 +613,7 @@ ZSTDLIB_API ZSTD_CDict* ZSTD_initStaticCDict_advanced_opaque(
                       const void* dict, size_t dictSize,
                             const ZSTD_CCtx_params* params);
 
-/* TODO */
-ZSTDLIB_API ZSTD_CCtx_params* ZSTD_createCCtxParams(void);
-/*! ZSTD_resetCCtxParams() :
- * Reset params to default, with the default compression level. */
-ZSTDLIB_API size_t ZSTD_resetCCtxParams(ZSTD_CCtx_params* params);
-ZSTDLIB_API size_t ZSTD_initCCtxParams(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params);
-ZSTDLIB_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
+
 
 /*! ZSTD_getCParams() :
 *   @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
@@ -1013,21 +1007,6 @@ typedef enum {
  *  @result : 0, or an error code (which can be tested with ZSTD_isError()). */
 ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned value);
 
-/*! ZSTD_CCtxParam_setParameter() :
- *  Similar to ZSTD_CCtx_setParameter.
- *  Set one compression parameter, selected by enum ZSTD_cParameter.
- *  Parameters must be applied to a ZSTD_CCtx using ZSTD_CCtx_applyCCtxParams().
- *  Note : when `value` is an enum, cast it to unsigned for proper type checking.
- *  @result : 0, or an error code (which can be tested with ZSTD_isError()). */
-ZSTDLIB_API size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, unsigned value);
-
-/*! ZSTD_CCtx_applyCCtxParams() :
- * Apply a set of ZSTD_CCtx_params to the compression context.
- * This must be done before the dictionary is loaded.
- * The pledgedSrcSize is treated as unknown.
- * Multithreading parameters are applied only if nbThreads > 1. */
-ZSTDLIB_API size_t ZSTD_CCtx_applyCCtxParams(ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params);
-
 /*! ZSTD_CCtx_setPledgedSrcSize() :
  *  Total input data size to be compressed as a single frame.
  *  This value will be controlled at the end, and result in error if not respected.
@@ -1131,7 +1110,44 @@ size_t ZSTD_compress_generic_simpleArgs (
                       const void* src, size_t srcSize, size_t* srcPos,
                             ZSTD_EndDirective endOp);
 
+/** ZSTD_CCtx_params :
+ *
+ *  - ZSTD_createCCtxParams() : Create a ZSTD_CCtx_params structure
+ *  - ZSTD_CCtxParam_setParameter() : Push parameters one by one into an
+ *  existing ZSTD_CCtx_params structure. This is similar to
+ *  ZSTD_CCtx_setParameter().
+ *  - ZSTD_CCtx_applyCCtxParams() : Apply parameters to an existing CCtx. These
+ *  parameters will be applied to all subsequent compression jobs.
+ *  - ZSTD_compress_generic() : Do compression using the CCtx.
+ *  - ZSTD_freeCCtxParams() : Free the memory. */
 
+ZSTDLIB_API ZSTD_CCtx_params* ZSTD_createCCtxParams(void);
+
+/*! ZSTD_resetCCtxParams() :
+ *  Reset params to default, with the default compression level. */
+ZSTDLIB_API size_t ZSTD_resetCCtxParams(ZSTD_CCtx_params* params);
+
+/*! ZSTD_initCCtxParams() :
+ *  Set the compression and frame parameters of cctxParams according to params.
+ *  All other parameters are reset to their default values. */
+ZSTDLIB_API size_t ZSTD_initCCtxParams(ZSTD_CCtx_params* cctxParams, ZSTD_parameters params);
+
+ZSTDLIB_API size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
+
+/*! ZSTD_CCtxParam_setParameter() :
+ *  Similar to ZSTD_CCtx_setParameter.
+ *  Set one compression parameter, selected by enum ZSTD_cParameter.
+ *  Parameters must be applied to a ZSTD_CCtx using ZSTD_CCtx_applyCCtxParams().
+ *  Note : when `value` is an enum, cast it to unsigned for proper type checking.
+ *  @result : 0, or an error code (which can be tested with ZSTD_isError()). */
+ZSTDLIB_API size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, unsigned value);
+
+/*! ZSTD_CCtx_applyCCtxParams() :
+ * Apply a set of ZSTD_CCtx_params to the compression context.
+ * This must be done before the dictionary is loaded.
+ * The pledgedSrcSize is treated as unknown.
+ * Multithreading parameters are applied only if nbThreads > 1. */
+ZSTDLIB_API size_t ZSTD_CCtx_applyCCtxParams(ZSTD_CCtx* cctx, const ZSTD_CCtx_params* params);
 
 /**
     Block functions