Docs: Document garbage collector threshold doubling and its memory spike trade-off.

dylan-sutton-chavez · dylan-sutton-chavez · commit 4d66bc7d5f99 · 2026-04-17T05:05:53.000-06:00
diff --git a/compiler/src/modules/vm/types.rs b/compiler/src/modules/vm/types.rs
@@ -501,6 +501,7 @@ impl HeapPool {
             }
         }
 
+        // Garbage collector threshold doubles after each sweep: fewer collections but temporary 2x memory spikes.
         self.gc_threshold = (self.live * 2).max(512);
         self.alloc_count  = 0;
         if self.free_list.len() > 65_536 { self.free_list.truncate(65_536); }

Original file line number	Diff line number	Diff line change
`@@ -501,6 +501,7 @@ impl HeapPool {`
`501`	`501`	`}`
`502`	`502`	`}`
`503`	`503`
	`504`	`+ // Garbage collector threshold doubles after each sweep: fewer collections but temporary 2x memory spikes.`
`504`	`505`	`self.gc_threshold = (self.live * 2).max(512);`
`505`	`506`	`self.alloc_count = 0;`
`506`	`507`	`if self.free_list.len() > 65_536 { self.free_list.truncate(65_536); }`