From 385199d4b5c689287dc4a656b7ecfb30c50b76b7 Mon Sep 17 00:00:00 2001
From: Christopher Haster <geky@geky.net>
Date: Sat, 19 Apr 2025 15:39:15 -0500
Subject: [PATCH] Tweaked some crystallization comments

- Trying to prefer crystal over compact verbiage to try to avoid
  confusion with metadata/rbyd compaction

- crystal_thresh >= block_size implying a fully-fragmented file was a
  mistake, it should be crystal_thresh > block_size.

  crystal_thresh == block_size has the behavior of waiting until the
  last moment to crystallize a block, but this still breaks the
  fully-fragmented random-write guarantee.

  This changed during development, so the comment was probably just
  outdated.
---
 lfs.c | 31 +++++++++++++++++--------------
 lfs.h | 10 +++++-----
 2 files changed, 22 insertions(+), 19 deletions(-)

diff --git a/lfs.c b/lfs.c
index cdb0d4a4..362cbfe9 100644
--- a/lfs.c
+++ b/lfs.c
@@ -11829,7 +11829,7 @@ static int lfsr_file_flush_(lfs_t *lfs, lfsr_file_t *file,
                     off = bptr.data.u.disk.off;
                     eoff = lfsr_bptr_cksize(&bptr);
                     cksum = lfsr_bptr_cksum(&bptr);
-                    goto compact;
+                    goto crystallize;
                 }
             }
         }
@@ -11873,11 +11873,12 @@ static int lfsr_file_flush_(lfs_t *lfs, lfsr_file_t *file,
             goto fragment;
         }
 
-        // exceeded our crystallization threshold? compact into a new block
+        // exceeded our crystallization threshold? crystallize into a
+        // new block
 
-        // before we can compact we need to figure out the best block
-        // alignment, we use the entry immediately to the left of our
-        // crystal for this
+        // before we can crystallize we need to figure out the best
+        // block alignment, we use the entry immediately to the left of
+        // our crystal for this
         block_start = crystal_start;
         if (crystal_start > 0
                 && file->b.shrub.weight > 0
@@ -11920,7 +11921,7 @@ static int lfsr_file_flush_(lfs_t *lfs, lfsr_file_t *file,
                     off = bptr.data.u.disk.off;
                     eoff = lfsr_bptr_cksize(&bptr);
                     cksum = lfsr_bptr_cksum(&bptr);
-                    goto compact;
+                    goto crystallize;
                 }
 
             // no? is our left neighbor at least our left block neighbor?
@@ -11947,8 +11948,8 @@ static int lfsr_file_flush_(lfs_t *lfs, lfsr_file_t *file,
         eoff = 0;
         cksum = 0;
 
-    compact:;
-        // compact data into our block
+    crystallize:;
+        // crystallize data into our block
         //
         // eagerly merge any right neighbors we see unless that would
         // put us over our block size
@@ -12083,10 +12084,12 @@ static int lfsr_file_flush_(lfs_t *lfs, lfsr_file_t *file,
             eoff += d;
         }
 
-        // A bit of a hack here, we need to truncate our block to prog_size
-        // alignment to avoid padding issues. Doing this retroactively to
-        // the pcache greatly simplifies the above loop, though we may end
-        // up reading more than is strictly necessary.
+        // a bit of a hack here, we need to truncate our block to
+        // prog_size alignment to avoid padding issues
+        //
+        // doing this retroactively to the pcache greatly simplifies the
+        // above loop, though we may end up reading more than is
+        // strictly necessary
         lfs_ssize_t d = eoff % lfs->cfg->prog_size;
         lfs->pcache.size -= d;
         block_end -= d;
@@ -12130,8 +12133,8 @@ static int lfsr_file_flush_(lfs_t *lfs, lfsr_file_t *file,
             file->eoff = eoff;
         }
 
-        // note compacting fragments -> blocks may not actually make any
-        // progress on flushing the buffer on the first pass
+        // note crystallizing fragments -> blocks may not actually make
+        // any progress on flushing the buffer on the first pass
         d = lfs_max(pos, block_end) - pos;
         pos += d;
         buffer += lfs_min(d, size);
diff --git a/lfs.h b/lfs.h
index ca81c976..03233c23 100644
--- a/lfs.h
+++ b/lfs.h
@@ -446,16 +446,16 @@ struct lfs_config {
     lfs_size_t fragment_size;
 
     // Threshold for compacting multiple fragments into a block. Smaller
-    // values will compact more eagerly, reducing disk usage, but increasing
-    // the cost of random-writes.
+    // values will crystallize more eagerly, reducing disk usage, but
+    // increasing the cost of random-writes.
     //
-    // 0 only writes blocks, minimizing disk usage, while -1 or any value >=
+    // 0 only writes blocks, minimizing disk usage, while -1 or any value >
     // block_size only writes fragments, minimizing random-write cost.
     lfs_size_t crystal_thresh;
 
     // Threshold for breaking a block into fragments. Smaller values will
-    // break more lazily, reducing random-write cost, but risk leaving blocks
-    // around with wasted storage.
+    // fragment more lazily, reducing random-write cost, but risk higher
+    // disk usage.
     //
     // This can be set lower than crystal_thresh to prevent repeated
     // compact/break operations in files with heavy random writes, at a