clarified documentation related to refPrefix()
diff --git a/doc/zstd_manual.html b/doc/zstd_manual.html
index ef7c87d..aae6d0f 100644
--- a/doc/zstd_manual.html
+++ b/doc/zstd_manual.html
@@ -939,18 +939,21 @@
Note 2 : CDict is just referenced, its lifetime must outlive CCtx.
</p></pre><BR>
-<pre><b>size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize);
-size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
+<pre><b>size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx,
+ const void* prefix, size_t prefixSize);
+size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx,
+ const void* prefix, size_t prefixSize,
+ ZSTD_dictContentType_e dictContentType);
</b><p> Reference a prefix (single-usage dictionary) for next compression job.
Decompression need same prefix to properly regenerate data.
- Prefix is **only used once**. Tables are discarded at end of compression job.
- Subsequent compression jobs will be done without prefix (if none is explicitly referenced).
- If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_CDict instead.
+ Prefix is **only used once**. Tables are discarded at end of compression job (ZSTD_e_end).
@result : 0, or an error code (which can be tested with ZSTD_isError()).
Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary
- Note 1 : Prefix buffer is referenced. It must outlive compression job.
+ Note 1 : Prefix buffer is referenced. It **must** outlive compression job.
+ Its contain must remain unmodified up to end of compression (ZSTD_e_end).
Note 2 : Referencing a prefix involves building tables, which are dependent on compression parameters.
It's a CPU consuming operation, with non-negligible impact on latency.
+ If there is a need to use same prefix multiple times, consider loadDictionary instead.
Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent).
Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode.
</p></pre><BR>
@@ -1112,17 +1115,23 @@
</p></pre><BR>
-<pre><b>size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize);
-size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
+<pre><b>size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx,
+ const void* prefix, size_t prefixSize);
+size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx,
+ const void* prefix, size_t prefixSize,
+ ZSTD_dictContentType_e dictContentType);
</b><p> Reference a prefix (single-usage dictionary) for next compression job.
- Prefix is **only used once**. It must be explicitly referenced before each frame.
- If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_DDict instead.
+ Prefix is **only used once**. Reference is discarded at end of frame.
+ End of frame is reached when ZSTD_DCtx_decompress_generic() returns 0.
@result : 0, or an error code (which can be tested with ZSTD_isError()).
Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary
- Note 2 : Prefix buffer is referenced. It must outlive compression job.
+ Note 2 : Prefix buffer is referenced. It **must** outlive decompression job.
+ Prefix buffer must remain unmodified up to the end of frame,
+ reached when ZSTD_DCtx_decompress_generic() returns 0.
Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent).
Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode.
Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost.
+ A fulldict prefix is more costly though.
</p></pre><BR>
diff --git a/lib/zstd.h b/lib/zstd.h
index aed0c72..57d3e5f 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -1129,18 +1129,21 @@
/*! ZSTD_CCtx_refPrefix() :
* Reference a prefix (single-usage dictionary) for next compression job.
* Decompression need same prefix to properly regenerate data.
- * Prefix is **only used once**. Tables are discarded at end of compression job.
- * Subsequent compression jobs will be done without prefix (if none is explicitly referenced).
- * If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_CDict instead.
+ * Prefix is **only used once**. Tables are discarded at end of compression job (ZSTD_e_end).
* @result : 0, or an error code (which can be tested with ZSTD_isError()).
* Special: Adding any prefix (including NULL) invalidates any previous prefix or dictionary
- * Note 1 : Prefix buffer is referenced. It must outlive compression job.
+ * Note 1 : Prefix buffer is referenced. It **must** outlive compression job.
+ * Its contain must remain unmodified up to end of compression (ZSTD_e_end).
* Note 2 : Referencing a prefix involves building tables, which are dependent on compression parameters.
* It's a CPU consuming operation, with non-negligible impact on latency.
+ * If there is a need to use same prefix multiple times, consider loadDictionary instead.
* Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent).
* Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode. */
-ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize);
-ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
+ZSTDLIB_API size_t ZSTD_CCtx_refPrefix(ZSTD_CCtx* cctx,
+ const void* prefix, size_t prefixSize);
+ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx,
+ const void* prefix, size_t prefixSize,
+ ZSTD_dictContentType_e dictContentType);
/*! ZSTD_CCtx_reset() :
* Return a CCtx to clean state.
@@ -1317,17 +1320,23 @@
/*! ZSTD_DCtx_refPrefix() :
* Reference a prefix (single-usage dictionary) for next compression job.
- * Prefix is **only used once**. It must be explicitly referenced before each frame.
- * If there is a need to use same prefix multiple times, consider embedding it into a ZSTD_DDict instead.
+ * Prefix is **only used once**. Reference is discarded at end of frame.
+ * End of frame is reached when ZSTD_DCtx_decompress_generic() returns 0.
* @result : 0, or an error code (which can be tested with ZSTD_isError()).
* Note 1 : Adding any prefix (including NULL) invalidates any previously set prefix or dictionary
- * Note 2 : Prefix buffer is referenced. It must outlive compression job.
+ * Note 2 : Prefix buffer is referenced. It **must** outlive decompression job.
+ * Prefix buffer must remain unmodified up to the end of frame,
+ * reached when ZSTD_DCtx_decompress_generic() returns 0.
* Note 3 : By default, the prefix is treated as raw content (ZSTD_dm_rawContent).
* Use ZSTD_CCtx_refPrefix_advanced() to alter dictMode.
* Note 4 : Referencing a raw content prefix has almost no cpu nor memory cost.
+ * A fulldict prefix is more costly though.
*/
-ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize);
-ZSTDLIB_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx, const void* prefix, size_t prefixSize, ZSTD_dictContentType_e dictContentType);
+ZSTDLIB_API size_t ZSTD_DCtx_refPrefix(ZSTD_DCtx* dctx,
+ const void* prefix, size_t prefixSize);
+ZSTDLIB_API size_t ZSTD_DCtx_refPrefix_advanced(ZSTD_DCtx* dctx,
+ const void* prefix, size_t prefixSize,
+ ZSTD_dictContentType_e dictContentType);
/*! ZSTD_DCtx_setMaxWindowSize() :
