AuroraMiddleware/zstd
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve comments and ordering

Browse Source
This commit is contained in:
Nick Terrell 2017-04-04 18:49:07 -07:00
parent 97693aff98
commit 9c7371b3ee
1 changed files with 65 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
contrib/linux-kernel/include/linux/zstd.h
View File

@ -32,10 +32,6 @@
The compression ratio achievable on small data can be highly improved using compression with a dictionary in:
- a single step (described as Simple dictionary API)
- a single step, reusing a dictionary (described as Fast dictionary API)
Advanced experimental functions can be accessed using #define ZSTD_STATIC_LINKING_ONLY before including zstd.h.
These APIs shall never be used with a dynamic library.
They are not "stable", their definition may change in the future. Only static linking is allowed.
*********************************************************************************************************/
/*------ Version ------*/
@ -121,28 +117,51 @@ typedef struct {
ZSTD_frameParameters fParams;
} ZSTD_parameters;
size_t ZSTD_CCtxWorkspaceBound(ZSTD_compressionParameters params);
/*! ZSTD_getCParams() :
* @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
* `estimatedSrcSize` value is optional, select 0 if not known */
ZSTDLIB_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
/*! ZSTD_getParams() :
* same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`.
* All fields of `ZSTD_frameParameters` are set to default (0) */
ZSTDLIB_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
/*! ZSTD_CCtxWorkspaceBound() :
* Returns the minimum amount of memory that needs to be passed to ZSTD_createCCtx() in order to compress with `params.cParams`
* or a `cdict` created with `params.cParams`. */
size_t ZSTD_CCtxWorkspaceBound(ZSTD_compressionParameters cParams);
/*= Compression context
* When compressing many times,
* it is recommended to allocate a context just once, and re-use it for each successive compression operation.
* This will make workload friendlier for system's memory.
* The context pointer is placed in `workspace`, which must outlive the returned context.
* Use one context per thread for parallel execution in multi-threaded environments. */
typedef struct ZSTD_CCtx_s ZSTD_CCtx;
ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void* workspace, size_t workspaceSize);
/*! ZSTD_compressCCtx() :
Same as ZSTD_compress(), requires an allocated ZSTD_CCtx (see ZSTD_createCCtx()). */
* Same as ZSTD_compress(), requires an allocated ZSTD_CCtx (see ZSTD_createCCtx()).
* Note : The workspace passed to ZSTD_createCCtx() must have been at least ZSTD_CCtxWorkspaceBound(params.cParams) bytes. */
ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, ZSTD_parameters params);
/*! ZSTD_compress_usingDict() :
* Compression using a predefined Dictionary (see dictBuilder/zdict.h).
* Note : The workspace passed to ZSTD_createCCtx() must have been at least ZSTD_CCtxWorkspaceBound(params.cParams) bytes.
* Note : This function loads the dictionary, resulting in significant startup delay.
* Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, const void *dict, size_t dictSize, ZSTD_parameters params);
/*! ZSTD_DCtxWorkspaceBound() :
* Returns the minimum amount of memory that needs to be passed to ZSTD_createDCtx(). */
size_t ZSTD_DCtxWorkspaceBound(void);
/*= Decompression context
* When decompressing many times,
* it is recommended to allocate a context just once, and re-use it for each successive compression operation.
* This will make workload friendlier for system's memory.
* The context pointer is placed in `workspace`, which must outlive the returned context.
* `workspace` must be at least ZSTD_DCtxWorkspaceBound() bytes.
* Use one context per thread for parallel execution in multi-threaded environments. */
typedef struct ZSTD_DCtx_s ZSTD_DCtx;
ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void* workspace, size_t workspaceSize);
@ -151,12 +170,19 @@ ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void* workspace, size_t workspaceSize);
* Same as ZSTD_decompress(), requires an allocated ZSTD_DCtx (see ZSTD_createDCtx()). */
ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
/*! ZSTD_decompress_usingDict() :
* Decompression using a predefined Dictionary (see dictBuilder/zdict.h).
* Dictionary must be identical to the one used during compression.
* Note : This function loads the dictionary, resulting in significant startup delay.
* Note : When `dict == NULL || dictSize < 8` no dictionary is used. */
ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, const void *dict, size_t dictSize);
/****************************
* Fast dictionary API
****************************/
size_t ZSTD_CDictWorkspaceBound(ZSTD_compressionParameters params);
/*! ZSTD_CDictWorkspaceBound() :
* Returns the minimum amount of memory that needs to be passed to ZSTD_createCDict() when called with the given `params.cParams`. */
size_t ZSTD_CDictWorkspaceBound(ZSTD_compressionParameters cParams);
typedef struct ZSTD_CDict_s ZSTD_CDict;
@ -164,7 +190,9 @@ typedef struct ZSTD_CDict_s ZSTD_CDict;
* When compressing multiple messages / blocks with the same dictionary, it's recommended to load it just once.
* ZSTD_createCDict() will create a digested dictionary, ready to start future compression operations without startup delay.
* ZSTD_CDict can be created once and used by multiple threads concurrently, as its usage is read-only.
* `dictBuffer` content is referenced, and it must remain accessible throughout the lifetime of the CDict */
* `dictBuffer` content is referenced, and it must remain accessible throughout the lifetime of the CDict.
* The cdict pointer is placed in `workspace`, which must outlive the returned cdict.
* `workspace` must be at least ZSTD_CDictWorkspaceBound(params.cParams) bytes. */
ZSTDLIB_API ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize, ZSTD_parameters params, void* workspace, size_t workspaceSize);
/*! ZSTD_compress_usingCDict() :
@ -177,13 +205,17 @@ ZSTDLIB_API size_t ZSTD_compress_usingCDict(ZSTD_CCtx* cctx,
const ZSTD_CDict* cdict);
/*! ZSTD_DDictWorkspaceBound() :
* Returns the minimum amount of memory that needs to be passed to ZSTD_createDDict(). */
size_t ZSTD_DDictWorkspaceBound(void);
typedef struct ZSTD_DDict_s ZSTD_DDict;
/*! ZSTD_createDDict() :
* Create a digested dictionary, ready to start decompression operation without startup delay.
* `dictBuffer` content is referenced, and it must remain accessible throughout the lifetime of the DDict */
* `dictBuffer` content is referenced, and it must remain accessible throughout the lifetime of the DDict.
* The ddict pointer is placed in `workspace`, which must outlive the returned ddict.
* `workspace` must be at least ZSTD_DDictWorkspaceBound() bytes. */
ZSTDLIB_API ZSTD_DDict* ZSTD_createDDict(const void* dictBuffer, size_t dictSize, void* workspace, size_t workspaceSize);
/*! ZSTD_decompress_usingDDict() :
@ -219,13 +251,12 @@ typedef struct ZSTD_outBuffer_s {
* A ZSTD_CStream object is required to track streaming operation.
* Use ZSTD_createCStream() and ZSTD_freeCStream() to create/release resources.
* ZSTD_CStream objects can be reused multiple times on consecutive compression operations.
* It is recommended to re-use ZSTD_CStream in situations where many streaming operations will be achieved consecutively,
* since it will play nicer with system's memory, by re-using already allocated memory.
* It is recommended to re-use ZSTD_CStream in situations where many streaming operations will be achieved consecutively.
* Use one separate ZSTD_CStream per thread for parallel execution.
*
* Start a new compression by initializing ZSTD_CStream.
* Use ZSTD_initCStream() to start a new compression operation.
* Use ZSTD_initCStream_usingDict() or ZSTD_initCStream_usingCDict() for a compression which requires a dictionary (experimental section)
* Use ZSTD_initCStream_usingCDict() for a compression which requires a dictionary.
*
* Use ZSTD_compressStream() repetitively to consume input stream.
* The function will automatically update both `pos` fields.
@ -252,11 +283,22 @@ typedef struct ZSTD_outBuffer_s {
*
* *******************************************************************/
size_t ZSTD_CStreamWorkspaceBound(ZSTD_compressionParameters params);
/*! ZSTD_CStreamWorkspaceBound() :
* Returns the minimum amount of memory that needs to be passed to ZSTD_createCStream() or ZSTD_createCStream_usingCDict()
* when called with the given `params.cParams` or `cdict` created with `params.cParams`. */
size_t ZSTD_CStreamWorkspaceBound(ZSTD_compressionParameters cParams);
typedef struct ZSTD_CStream_s ZSTD_CStream;
/*===== ZSTD_CStream management functions =====*/
/*! ZSTD_createCStream() :
* Creates a cstream using params.
* Callers may optionally provide the size of the source they intend to compress, or pass 0 if unknown.
* The stream is placed in `workspace`, which must outlive the returned stream.
* `workspace` must be at least ZSTD_CStreamWorkspaceBound(params.cParams) bytes. */
ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream(ZSTD_parameters params, unsigned long long pledgedSrcSize, void* workspace, size_t workspaceSize);
/*! ZSTD_createCStream_usingCDict() :
* Similar to ZSTD_createCStream(), but use the given preprocessed dictionary.
*/
ZSTDLIB_API ZSTD_CStream* ZSTD_createCStream_usingCDict(const ZSTD_CDict* cdict, unsigned long long pledgedSrcSize, void* workspace, size_t workspaceSize);
/*===== Streaming compression functions =====*/
@ -292,11 +334,19 @@ ZSTDLIB_API size_t ZSTD_CStreamOutSize(void); /**< recommended size for output
* The return value is a suggested next input size (a hint to improve latency) that will never load more than the current frame.
* *******************************************************************************/
/*! ZSTD_DStreamWorkspaceBound() :
* Returns the minimum amount of memory that needs to be passed to ZSTD_createDStream() to decompress frames with windowSize <= maxWindowSize. */
size_t ZSTD_DStreamWorkspaceBound(size_t maxWindowSize);
typedef struct ZSTD_DStream_s ZSTD_DStream;
/*===== ZSTD_DStream management functions =====*/
/*! ZSTD_createDStream() :
* Creates a dstream that can decompress frames with windowSize up to maxWindowSize.
* The stream is placed in `workspace`, which must outlive the returned stream.
* `workspace` must be at least ZSTD_DStreamWorkspaceBound(maxWindowSize) bytes. */
ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream(size_t maxWindowSize, void* workspace, size_t workspaceSize);
/*! ZSTD_createDStream_usingDDict() :
* Similar to ZSTD_createCStream(), but use the given preprocessed dictionary. */
ZSTDLIB_API ZSTD_DStream* ZSTD_createDStream_usingDDict(size_t maxWindowSize, const ZSTD_DDict* ddict, void* workspace, size_t workspaceSize);
/*===== Streaming decompression functions =====*/
@ -307,14 +357,6 @@ ZSTDLIB_API size_t ZSTD_DStreamInSize(void); /*!< recommended size for input
ZSTDLIB_API size_t ZSTD_DStreamOutSize(void); /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */
/****************************************************************************************
* START OF ADVANCED AND EXPERIMENTAL FUNCTIONS
* The definitions in this section are considered experimental.
* They should never be used with a dynamic library, as they may change in the future.
* They are provided for advanced usages.
* Use them only in association with static linking.
* ***************************************************************************************/
/* --- Constants ---*/
#define ZSTD_MAGICNUMBER 0xFD2FB528 /* >= v0.8.0 */
#define ZSTD_MAGIC_SKIPPABLE_START 0x184D2A50U
@ -397,16 +439,6 @@ ZSTDLIB_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t
/***************************************
* Advanced compression functions
***************************************/
/*! ZSTD_getCParams() :
* @return ZSTD_compressionParameters structure for a selected compression level and estimated srcSize.
* `estimatedSrcSize` value is optional, select 0 if not known */
ZSTDLIB_API ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
/*! ZSTD_getParams() :
* same as ZSTD_getCParams(), but @return a full `ZSTD_parameters` object instead of sub-component `ZSTD_compressionParameters`.
* All fields of `ZSTD_frameParameters` are set to default (0) */
ZSTDLIB_API ZSTD_parameters ZSTD_getParams(int compressionLevel, unsigned long long estimatedSrcSize, size_t dictSize);
/*! ZSTD_checkCParams() :
* Ensure param values remain within authorized range */
ZSTDLIB_API size_t ZSTD_checkCParams(ZSTD_compressionParameters params);