From 2a9876a885ba671178458e7fa98738eb8aa21420 Mon Sep 17 00:00:00 2001
From: Jemma Issroff <jemmaissroff@gmail.com>
Date: Mon, 20 Sep 2021 14:40:55 -0400
Subject: Enhance documentation on GC.stat (#4843)

---
 gc.rb | 86 +++++++++++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 56 insertions(+), 30 deletions(-)

diff --git a/gc.rb b/gc.rb
index 8a00b406ce..c0459b0beb 100644
--- a/gc.rb
+++ b/gc.rb
@@ -128,39 +128,65 @@ module GC
   #
   #  Returns a Hash containing information about the GC.
   #
-  #  The hash includes information about internal statistics about GC such as:
-  #
-  #      {
-  #          :count=>0,
-  #          :heap_allocated_pages=>24,
-  #          :heap_sorted_length=>24,
-  #          :heap_allocatable_pages=>0,
-  #          :heap_available_slots=>9783,
-  #          :heap_live_slots=>7713,
-  #          :heap_free_slots=>2070,
-  #          :heap_final_slots=>0,
-  #          :heap_marked_slots=>0,
-  #          :heap_eden_pages=>24,
-  #          :heap_tomb_pages=>0,
-  #          :total_allocated_pages=>24,
-  #          :total_freed_pages=>0,
-  #          :total_allocated_objects=>7796,
-  #          :total_freed_objects=>83,
-  #          :malloc_increase_bytes=>2389312,
-  #          :malloc_increase_bytes_limit=>16777216,
-  #          :minor_gc_count=>0,
-  #          :major_gc_count=>0,
-  #          :remembered_wb_unprotected_objects=>0,
-  #          :remembered_wb_unprotected_objects_limit=>0,
-  #          :old_objects=>0,
-  #          :old_objects_limit=>0,
-  #          :oldmalloc_increase_bytes=>2389760,
-  #          :oldmalloc_increase_bytes_limit=>16777216
-  #      }
-  #
   #  The contents of the hash are implementation specific and may be changed in
   #  the future.
   #
+  #  The hash includes information about internal statistics about GC such as:
+  #
+  #  [count]
+  #    The total number of garbage collections ran since application start
+  #    (count includes both minor and major garbage collections)
+  #  [heap_allocated_pages]
+  #    The total number of `:heap_eden_pages` + `:heap_tomb_pages`
+  #  [heap_sorted_length]
+  #    The number of pages that can fit into the buffer that holds references to
+  #    all pages
+  #  [heap_allocatable_pages]
+  #    The total number of pages the application could allocate without additional GC
+  #  [heap_available_slots]
+  #    The total number of slots in all `:heap_allocated_pages`
+  #  [heap_live_slots]
+  #    The total number of slots which contain live objects
+  #  [heap_free_slots]
+  #    The total number of slots which do not contain live objects
+  #  [heap_final_slots]
+  #    The total number of slots with pending finalizers to be run
+  #  [heap_marked_slots]
+  #    The total number of objects marked in the last GC
+  #  [heap_eden_pages]
+  #    The total number of pages which contain at least one live slot
+  #  [heap_tomb_pages]
+  #    The total number of pages which do not contain any live slots
+  #  [total_allocated_pages]
+  #    The cumulative number of pages allocated since application start
+  #  [total_freed_pages]
+  #    The cumulative number of pages freed since application start
+  #  [total_allocated_objects]
+  #    The cumulative number of objects allocated since application start
+  #  [total_freed_objects]
+  #    The cumulative number of objects freed since application start
+  #  [malloc_increase_bytes]
+  #    Amount of memory allocated on the heap for objects. Decreased by any GC
+  #  [malloc_increase_bytes_limit]
+  #    When `:malloc_increase_bytes` crosses this limit, GC is triggered
+  #  [minor_gc_count]
+  #    The total number of minor garbage collections run since process start
+  #  [major_gc_count]
+  #    The total number of major garbage collections run since process start
+  #  [remembered_wb_unprotected_objects]
+  #    The total number of objects without write barriers
+  #  [remembered_wb_unprotected_objects_limit]
+  #    When `:remembered_wb_unprotected_objects` crosses this limit,
+  #    major GC is triggered
+  #  [old_objects]
+  #    Number of live, old objects which have survived at least 3 garbage collections
+  #  [old_objects_limit]
+  #    When `:old_objects` crosses this limit, major GC is triggered
+  #  [oldmalloc_increase_bytes]
+  #    Amount of memory allocated on the heap for objects. Decreased by major GC
+  #  [oldmalloc_increase_bytes_limit]
+  #    When `:old_malloc_increase_bytes` crosses this limit, major GC is triggered
+  #
   #  If the optional argument, hash, is given,
   #  it is overwritten and returned.
   #  This is intended to avoid probe effect.
-- 
cgit v1.2.3