From 226aa852944867df0aba8f1ebee8d686c9230500 Mon Sep 17 00:00:00 2001
From: Julien Portalier <julien@portalier.com>
Date: Thu, 17 Apr 2025 11:49:49 +0200
Subject: [PATCH 1/4] Document the GC::Stats properties

---
 src/gc.cr | 39 +++++++++++++++++++++++++++++++--------
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/src/gc.cr b/src/gc.cr
index e7254a4a140a..a006147d4ffb 100644
--- a/src/gc.cr
+++ b/src/gc.cr
@@ -47,14 +47,37 @@ fun __crystal_realloc64(ptr : Void*, size : UInt64) : Void*
 end
 
 module GC
-  record Stats,
-    # collections : UInt64,
-    # bytes_found : Int64,
-    heap_size : UInt64,
-    free_bytes : UInt64,
-    unmapped_bytes : UInt64,
-    bytes_since_gc : UInt64,
-    total_bytes : UInt64
+  struct Stats
+    # The system memory allocated by the GC for its HEAP, in bytes. The memory
+    # may or may not have been allocated by the OS (for example some pages
+    # haven't been accessed). The number can grow and shrink as needed by the
+    # process.
+    getter heap_size : UInt64
+
+    # Number of free bytes in the GC HEAP. The number is relative the
+    # `#heap_size`.
+    getter free_bytes : UInt64
+
+    # The system memory returned to the OS by the GC but that can be reallocated
+    # at any time to grow the GC HEAP. The OS may have freed the memory already,
+    # or keep it allocated until there is memory pressure.
+    getter unmapped_bytes : UInt64
+
+    # Total memory allocated by the GC into its HEAP since the last GC
+    # collection, in bytes.
+    getter bytes_since_gc : UInt64
+
+    # Total memory allocated by the GC into its HEAP since the program started,
+    # in bytes. The number keeps growing indefinitely until the integer wraps
+    # back to zero.
+    getter total_bytes : UInt64
+
+    # getter collections : UInt64
+    # getter bytes_found : Int64
+
+    def initialize(@heap_size, @free_bytes, @unmapped_bytes, @bytes_since_gc, @total_bytes)
+    end
+  end
 
   record ProfStats,
     heap_size : UInt64,

From 17606fb9757f55ddc97611fb859c371284915674 Mon Sep 17 00:00:00 2001
From: Julien Portalier <julien@portalier.com>
Date: Fri, 18 Apr 2025 13:17:39 +0200
Subject: [PATCH 2/4] Fix: more precise documentation

---
 src/gc.cr | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/gc.cr b/src/gc.cr
index a006147d4ffb..696c401953bb 100644
--- a/src/gc.cr
+++ b/src/gc.cr
@@ -54,13 +54,16 @@ module GC
     # process.
     getter heap_size : UInt64
 
-    # Number of free bytes in the GC HEAP. The number is relative the
-    # `#heap_size`.
+    # Approximate number of free bytes in the GC HEAP. The number is relative to
+    # the `#heap_size`. The reported value is pessimistic, there might be more
+    # free bytes in reality.
     getter free_bytes : UInt64
 
-    # The system memory returned to the OS by the GC but that can be reallocated
-    # at any time to grow the GC HEAP. The OS may have freed the memory already,
-    # or keep it allocated until there is memory pressure.
+    # The size (in bytes) of virtual system memory that the GC returned to the
+    # OS when shrinking its HEAP. The OS may have reclaimed the memory already,
+    # reducing the resident memory usage, or may do so later (for example on
+    # memory pressure). The GC will reuse this memory when it needs to grow its
+    # HEAP again.
     getter unmapped_bytes : UInt64
 
     # Total memory allocated by the GC into its HEAP since the last GC

From 316a958c1308ac43b23e594ee3a7296661918520 Mon Sep 17 00:00:00 2001
From: Julien Portalier <julien@portalier.com>
Date: Fri, 18 Apr 2025 13:17:56 +0200
Subject: [PATCH 3/4] Cleanup

---
 src/gc.cr | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/gc.cr b/src/gc.cr
index 696c401953bb..90c87924bdfd 100644
--- a/src/gc.cr
+++ b/src/gc.cr
@@ -75,9 +75,6 @@ module GC
     # back to zero.
     getter total_bytes : UInt64
 
-    # getter collections : UInt64
-    # getter bytes_found : Int64
-
     def initialize(@heap_size, @free_bytes, @unmapped_bytes, @bytes_since_gc, @total_bytes)
     end
   end

From 2d2e7bf5bff38306a7c980251e21d36d867cdeb4 Mon Sep 17 00:00:00 2001
From: Julien Portalier <julien@portalier.com>
Date: Fri, 18 Apr 2025 13:18:21 +0200
Subject: [PATCH 4/4] Add missing clone and copy_with methods + deprecate them

---
 src/gc.cr | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/gc.cr b/src/gc.cr
index 90c87924bdfd..9bb61034abb7 100644
--- a/src/gc.cr
+++ b/src/gc.cr
@@ -77,6 +77,16 @@ module GC
 
     def initialize(@heap_size, @free_bytes, @unmapped_bytes, @bytes_since_gc, @total_bytes)
     end
+
+    @[Deprecated]
+    def copy_with(heap_size = @heap_size, free_bytes = @free_bytes, unmapped_bytes = @unmapped_bytes, bytes_since_gc = @bytes_since_gc, total_bytes = @total_bytes)
+      self.class.new(heap_size, free_bytes, unmapped_bytes, bytes_since_gc, total_bytes)
+    end
+
+    @[Deprecated]
+    def clone
+      self.class.new(@heap_size.clone, @free_bytes.clone, @unmapped_bytes.clone, @bytes_since_gc.clone, @total_bytes.clone)
+    end
   end
 
   record ProfStats,