Improve Comments a Bit

diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c
index 4e0b76b1347bfc90c2165d7c2bb407d06561ba03..262efead5ecd1a9e840f6bf404f52097ad37bc82 100644 (file)
--- a/lib/compress/zstd_compress.c
+++ b/lib/compress/zstd_compress.c
@@ -53,7 +53,6 @@ size_t ZSTD_compressBound(size_t srcSize) {
  */
 static size_t ZSTD_workspace_align(size_t size, size_t align) {
     return size + align - 1 - ((size - 1) & (align - 1));
-    // return size + 3 - ((size - 1) & 3);
 }
 
 static void* ZSTD_workspace_reserve(ZSTD_CCtx_workspace* ws, size_t bytes, ZSTD_workspace_alloc_phase_e phase) {
@@ -165,10 +164,18 @@ static int ZSTD_workspace_bump_oversized_duration(ZSTD_CCtx_workspace* ws) {
     return 0;
 }
 
+/**
+ * Invalidates table allocations.
+ * All other allocations remain valid.
+ */
 static void ZSTD_workspace_clear_tables(ZSTD_CCtx_workspace* ws) {
     ws->tableEnd = ws->objectEnd;
 }
 
+/**
+ * Invalidates all buffer, aligned, and table allocations.
+ * Object allocations remain valid.
+ */
 static void ZSTD_workspace_clear(ZSTD_CCtx_workspace* ws) {
     DEBUGLOG(3, "wksp: clearing!");
     ZSTD_workspace_bump_oversized_duration(ws);

diff --git a/lib/compress/zstd_compress_internal.h b/lib/compress/zstd_compress_internal.h
index 7122675754992beb9d95bd77a86be4be35bc31ed..52d15544c26520501f3410a5cd43d41571e5a72e 100644 (file)
--- a/lib/compress/zstd_compress_internal.h
+++ b/lib/compress/zstd_compress_internal.h
@@ -262,7 +262,10 @@ typedef enum {
  * are divided into the following categories:
  *
  * - Static objects: this is optionally the enclosing ZSTD_CCtx or ZSTD_CDict,
- *   so that literally everything fits in a single buffer.
+ *   so that literally everything fits in a single buffer. Note: if present,
+ *   this must be the first object in the workspace, since ZSTD_free{CCtx,
+ *   CDict}() rely on a pointer comparison to see whether one or two frees are
+ *   required.
  *
  * - Fixed size objects: these are fixed-size, fixed-count objects that are
  *   nonetheless "dynamically" allocated in the workspace so that we can
@@ -277,13 +280,22 @@ typedef enum {
  *   uint32_t arrays, all of whose values are between 0 and (nextSrc - base).
  *   Their sizes depend on the cparams.
  *
+ * - Aligned: these buffers are used for various purposes that don't require
+ *   any initialization before they're used.
+ *
  * - Uninitialized memory: these buffers are used for various purposes that
  *   don't require any initialization before they're used. This means they can
  *   be moved around at no cost for a new compression.
- *   - I/O Buffers
  *
- * [workspace, workspace + workspaceSize)
- * []
+ * Allocating Memory:
+ *
+ * The various types of objects must be allocated in order, so they can be
+ * correctly packed into the workspace buffer. That order is:
+ *
+ * 1. Objects
+ * 2. Buffers
+ * 3. Aligned
+ * 4. Tables
  */
 typedef struct {
     void* workspace;