From 2abe0145b18ec5aba2367e35ebacd12c5150eac5 Mon Sep 17 00:00:00 2001
From: "W. Felix Handte" <w@felixhandte.com>
Date: Wed, 14 Aug 2019 16:55:12 -0400
Subject: [PATCH] Improve Comments a Bit

---
 lib/compress/zstd_compress.c          |  9 ++++++++-
 lib/compress/zstd_compress_internal.h | 20 ++++++++++++++++----
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c
index 4e0b76b13..262efead5 100644
--- 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 712267575..52d15544c 100644
--- 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;