- The following symbols and constants are currently considered - to join "stable API" status by v1.4.0. - The intention is that they should be able to become stable "as is", with no further modification. - It is also last chance to gather comments / suggestions on this API, - as the API is locked once reaching "stable" status. + The following symbols and constants are in "staging area" : + they are considered to join "stable API" status by v1.4.0. + The below proposal is created so that it's possible to make it stable "as is". + That being said, it's still possible to suggest modifications. + Staging is in fact last chance for changes, + because the API is locked once reaching "stable" status.@@ -478,7 +479,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); * They return an error otherwise. */ ZSTD_p_nbWorkers=400, /* Select how many threads will be spawned to compress in parallel. * When nbWorkers >= 1, triggers asynchronous mode : - * ZSTD_compress_generic() consumes some input, flush some output if possible, and immediately gives back control to caller, + * ZSTD_compress_generic() consumes input and flush output if possible, but immediately gives back control to caller, * while compression work is performed in parallel, within worker threads. * (note : a strong exception to this rule is when first invocation sets ZSTD_e_end : it becomes a blocking call). * More workers improve speed, but also increase memory usage. @@ -535,8 +536,8 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict); */ } ZSTD_cParameter;
unsigned ZSTD_cParam_lowerBound(ZSTD_cParameter cParam); -unsigned ZSTD_cParam_upperBound(ZSTD_cParameter cParam); +int ZSTD_cParam_lowerBound(ZSTD_cParameter cParam); +int ZSTD_cParam_upperBound(ZSTD_cParameter cParam);All parameters must respect lower/upper bounds, otherwise they will either trigger an error or be automatically clamped. @@ -545,14 +546,15 @@ unsigned ZSTD_cParam_upperBound(ZSTD_cParameter cParam);
-size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned value); +size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value);Set one compression parameter, selected by enum ZSTD_cParameter. + All parameters have valid bounds. Bounds can be queried using ZSTD_cParam_getBounds(). + Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter). Setting a parameter is generally only possible during frame initialization (before starting compression). Exception : when using multi-threading mode (nbWorkers >= 1), the following parameters can be updated _during_ compression (within same frame): => compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy. new parameters will be active for next job only (after a flush()). - Note : when original `value` type is not unsigned (like int, or enum), cast it to unsigned. @result : informational value (typically, value being effectively set, after clamping), or an error code (which can be tested with ZSTD_isError()).
@@ -1061,11 +1063,10 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
-size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, unsigned value); +size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value);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_setParametersUsingCCtxParams(). - 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()).
diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c index 8fbbb44fd..e6d926430 100644 --- a/lib/compress/zstd_compress.c +++ b/lib/compress/zstd_compress.c @@ -266,9 +266,9 @@ static int ZSTD_isUpdateAuthorized(ZSTD_cParameter param) } } -size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned value) +size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value) { - DEBUGLOG(4, "ZSTD_CCtx_setParameter (%u, %u)", (U32)param, value); + DEBUGLOG(4, "ZSTD_CCtx_setParameter (%i, %i)", (int)param, value); if (cctx->streamStage != zcss_init) { if (ZSTD_isUpdateAuthorized(param)) { cctx->cParamsChanged = 1; @@ -331,20 +331,20 @@ size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, unsigned v } } -size_t ZSTD_CCtxParam_setParameter( - ZSTD_CCtx_params* CCtxParams, ZSTD_cParameter param, unsigned value) +size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* CCtxParams, + ZSTD_cParameter param, int value) { - DEBUGLOG(4, "ZSTD_CCtxParam_setParameter (%u, %u)", (U32)param, value); + DEBUGLOG(4, "ZSTD_CCtxParam_setParameter (%i, %i)", (int)param, value); switch(param) { case ZSTD_p_format : - if (value > (unsigned)ZSTD_f_zstd1_magicless) + if (value > (int)ZSTD_f_zstd1_magicless) return ERROR(parameter_unsupported); CCtxParams->format = (ZSTD_format_e)value; return (size_t)CCtxParams->format; case ZSTD_p_compressionLevel : { - int cLevel = (int)value; /* cast expected to restore negative sign */ + int cLevel = value; if (cLevel > ZSTD_maxCLevel()) cLevel = ZSTD_maxCLevel(); if (cLevel) { /* 0 : does not change current level */ CCtxParams->compressionLevel = cLevel; @@ -390,7 +390,7 @@ size_t ZSTD_CCtxParam_setParameter( case ZSTD_p_compressionStrategy : if (value>0) /* 0 => use default */ - CLAMPCHECK(value, (unsigned)ZSTD_fast, (unsigned)ZSTD_btultra); + CLAMPCHECK(value, (int)ZSTD_fast, (int)ZSTD_btultra); CCtxParams->cParams.strategy = (ZSTD_strategy)value; return (size_t)CCtxParams->cParams.strategy; diff --git a/lib/zstd.h b/lib/zstd.h index 5789f018d..0e05b689a 100644 --- a/lib/zstd.h +++ b/lib/zstd.h @@ -408,11 +408,12 @@ ZSTDLIB_API size_t ZSTD_DStreamOutSize(void); /*!< recommended size for output /**************************************************************************************** * Candidate API for promotion to stable status **************************************************************************************** - * The following symbols and constants are currently considered - * to join "stable API" status by v1.4.0. - * The intention is that they should be able to become stable "as is", with no further modification. - * It is also last chance to gather comments / suggestions on this API, - * as the API is locked once reaching "stable" status. + * The following symbols and constants are in "staging area" : + * they are considered to join "stable API" status by v1.4.0. + * The below proposal is created so that it's possible to make it stable "as is". + * That being said, it's still possible to suggest modifications. + * Staging is in fact last chance for changes, + * because the API is locked once reaching "stable" status. * ***************************************************************************************/ @@ -572,7 +573,7 @@ typedef enum { * They return an error otherwise. */ ZSTD_p_nbWorkers=400, /* Select how many threads will be spawned to compress in parallel. * When nbWorkers >= 1, triggers asynchronous mode : - * ZSTD_compress_generic() consumes some input, flush some output if possible, and immediately gives back control to caller, + * ZSTD_compress_generic() consumes input and flush output if possible, but immediately gives back control to caller, * while compression work is performed in parallel, within worker threads. * (note : a strong exception to this rule is when first invocation sets ZSTD_e_end : it becomes a blocking call). * More workers improve speed, but also increase memory usage. @@ -637,21 +638,22 @@ typedef enum { * @return : requested bound (inclusive) * note : if the request specifies a non-existing parameter, it will return 0. */ -ZSTDLIB_API unsigned ZSTD_cParam_lowerBound(ZSTD_cParameter cParam); -ZSTDLIB_API unsigned ZSTD_cParam_upperBound(ZSTD_cParameter cParam); +ZSTDLIB_API int ZSTD_cParam_lowerBound(ZSTD_cParameter cParam); +ZSTDLIB_API int ZSTD_cParam_upperBound(ZSTD_cParameter cParam); /*! ZSTD_CCtx_setParameter() : * Set one compression parameter, selected by enum ZSTD_cParameter. + * All parameters have valid bounds. Bounds can be queried using ZSTD_cParam_getBounds(). + * Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter). * Setting a parameter is generally only possible during frame initialization (before starting compression). * Exception : when using multi-threading mode (nbWorkers >= 1), * the following parameters can be updated _during_ compression (within same frame): * => compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy. * new parameters will be active for next job only (after a flush()). - * Note : when original `value` type is not unsigned (like int, or enum), cast it to unsigned. * @result : informational value (typically, value being effectively set, after clamping), * 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); +ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value); /*! ZSTD_CCtx_setPledgedSrcSize() : * Total input data size to be compressed as a single frame. @@ -891,13 +893,13 @@ ZSTDLIB_API size_t ZSTD_decompress_generic(ZSTD_DCtx* dctx, /* compression parameter bounds */ #define ZSTD_WINDOWLOG_MAX_32 30 #define ZSTD_WINDOWLOG_MAX_64 31 -#define ZSTD_WINDOWLOG_MAX ((unsigned)(sizeof(size_t) == 4 ? ZSTD_WINDOWLOG_MAX_32 : ZSTD_WINDOWLOG_MAX_64)) +#define ZSTD_WINDOWLOG_MAX ((int)(sizeof(size_t) == 4 ? ZSTD_WINDOWLOG_MAX_32 : ZSTD_WINDOWLOG_MAX_64)) #define ZSTD_WINDOWLOG_MIN 10 #define ZSTD_HASHLOG_MAX ((ZSTD_WINDOWLOG_MAX < 30) ? ZSTD_WINDOWLOG_MAX : 30) #define ZSTD_HASHLOG_MIN 6 #define ZSTD_CHAINLOG_MAX_32 29 #define ZSTD_CHAINLOG_MAX_64 30 -#define ZSTD_CHAINLOG_MAX ((unsigned)(sizeof(size_t) == 4 ? ZSTD_CHAINLOG_MAX_32 : ZSTD_CHAINLOG_MAX_64)) +#define ZSTD_CHAINLOG_MAX ((int)(sizeof(size_t) == 4 ? ZSTD_CHAINLOG_MAX_32 : ZSTD_CHAINLOG_MAX_64)) #define ZSTD_CHAINLOG_MIN ZSTD_HASHLOG_MIN #define ZSTD_SEARCHLOG_MAX (ZSTD_WINDOWLOG_MAX-1) #define ZSTD_SEARCHLOG_MIN 1 @@ -1264,10 +1266,9 @@ ZSTDLIB_API size_t ZSTD_CCtxParams_init_advanced(ZSTD_CCtx_params* cctxParams, Z * 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_setParametersUsingCCtxParams(). - * 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); +ZSTDLIB_API size_t ZSTD_CCtxParam_setParameter(ZSTD_CCtx_params* params, ZSTD_cParameter param, int value); /*! ZSTD_CCtxParam_getParameter() : * Similar to ZSTD_CCtx_getParameter. diff --git a/programs/fileio.c b/programs/fileio.c index 465988654..02fdc55d1 100644 --- a/programs/fileio.c +++ b/programs/fileio.c @@ -533,7 +533,7 @@ static cRess_t FIO_createCResources(const char* dictFileName, int cLevel, CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_dictIDFlag, g_dictIDFlag) ); CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_checksumFlag, g_checksumFlag) ); /* compression level */ - CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionLevel, (unsigned)cLevel) ); + CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionLevel, cLevel) ); /* long distance matching */ CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_enableLongDistanceMatching, g_ldmFlag) ); CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_ldmHashLog, g_ldmHashLog) ); @@ -551,7 +551,7 @@ static cRess_t FIO_createCResources(const char* dictFileName, int cLevel, CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_searchLog, comprParams.searchLog) ); CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_minMatch, comprParams.searchLength) ); CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_targetLength, comprParams.targetLength) ); - CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionStrategy, (U32)comprParams.strategy) ); + CHECK( ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionStrategy, comprParams.strategy) ); /* multi-threading */ #ifdef ZSTD_MULTITHREAD DISPLAYLEVEL(5,"set nb workers = %u \n", g_nbWorkers); @@ -994,14 +994,14 @@ FIO_compressZstdFrame(const cRess_t* ressPtr, if (compressionLevel > ZSTD_maxCLevel()) compressionLevel = ZSTD_maxCLevel(); if (compressionLevel > g_maxAdaptLevel) compressionLevel = g_maxAdaptLevel; compressionLevel += (compressionLevel == 0); /* skip 0 */ - ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionLevel, (unsigned)compressionLevel); + ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionLevel, compressionLevel); } if (speedChange == faster) { DISPLAYLEVEL(6, "faster speed , lighter compression \n") compressionLevel --; if (compressionLevel < g_minAdaptLevel) compressionLevel = g_minAdaptLevel; compressionLevel -= (compressionLevel == 0); /* skip 0 */ - ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionLevel, (unsigned)compressionLevel); + ZSTD_CCtx_setParameter(ress.cctx, ZSTD_p_compressionLevel, compressionLevel); } speedChange = noChange; diff --git a/tests/fuzzer.c b/tests/fuzzer.c index 375a6c445..4e8086c30 100644 --- a/tests/fuzzer.c +++ b/tests/fuzzer.c @@ -235,7 +235,7 @@ static int FUZ_mallocTests_internal(unsigned seed, double compressibility, unsig ZSTD_CCtx* const cctx = ZSTD_createCCtx_advanced(cMem); ZSTD_outBuffer out = { outBuffer, outSize, 0 }; ZSTD_inBuffer in = { inBuffer, inSize, 0 }; - CHECK_Z( ZSTD_CCtx_setParameter(cctx, ZSTD_p_compressionLevel, (U32)compressionLevel) ); + CHECK_Z( ZSTD_CCtx_setParameter(cctx, ZSTD_p_compressionLevel, compressionLevel) ); CHECK_Z( ZSTD_CCtx_setParameter(cctx, ZSTD_p_nbWorkers, nbThreads) ); while ( ZSTD_compress_generic(cctx, &out, &in, ZSTD_e_end) ) {} ZSTD_freeCCtx(cctx); @@ -255,7 +255,7 @@ static int FUZ_mallocTests_internal(unsigned seed, double compressibility, unsig ZSTD_CCtx* const cctx = ZSTD_createCCtx_advanced(cMem); ZSTD_outBuffer out = { outBuffer, outSize, 0 }; ZSTD_inBuffer in = { inBuffer, inSize, 0 }; - CHECK_Z( ZSTD_CCtx_setParameter(cctx, ZSTD_p_compressionLevel, (U32)compressionLevel) ); + CHECK_Z( ZSTD_CCtx_setParameter(cctx, ZSTD_p_compressionLevel, compressionLevel) ); CHECK_Z( ZSTD_CCtx_setParameter(cctx, ZSTD_p_nbWorkers, nbThreads) ); CHECK_Z( ZSTD_compress_generic(cctx, &out, &in, ZSTD_e_continue) ); while ( ZSTD_compress_generic(cctx, &out, &in, ZSTD_e_end) ) {} @@ -1252,7 +1252,7 @@ static int basicUnitTests(U32 seed, double compressibility) params); if (ZSTD_isError(cSize_1pass)) goto _output_error; - CHECK( ZSTD_CCtx_setParameter(cctx, ZSTD_p_compressionLevel, (unsigned)compressionLevel) ); + CHECK( ZSTD_CCtx_setParameter(cctx, ZSTD_p_compressionLevel, compressionLevel) ); { ZSTD_inBuffer in = { CNBuffer, srcSize, 0 }; ZSTD_outBuffer out = { compressedBuffer, compressedBufferSize, 0 }; size_t const compressionResult = ZSTD_compress_generic(cctx, &out, &in, ZSTD_e_end);