rbs 3.10.0 → 4.0.0.dev.1

data/core/gc.rbs

@@ -160,65 +160,81 @@ module GC
   # <!--
   #   rdoc-file=gc.rb
   #   - GC.config -> hash
-  #   - GC.config(hash_to_merge) -> hash
+  #   - GC.config(hash) -> hash
   # -->
-  # This method is implementation-specific to CRuby.
-  #
-  # Sets or gets information about the current GC configuration.
+  # Sets or gets information about the current GC config.
   #
   # Configuration parameters are GC implementation-specific and may change without
   # notice.
   #
-  # With no argument given, returns a hash containing the configuration:
+  # This method can be called without parameters to retrieve the current config as
+  # a `Hash` with `Symbol` keys.
+  #
+  # This method can also be called with a `Hash` argument to assign values to
+  # valid config keys. Config keys missing from the passed `Hash` will be left
+  # unmodified.
+  #
+  # If a key/value pair is passed to this function that does not correspond to a
+  # valid config key for the GC implementation being used, no config will be
+  # updated, the key will be present in the returned Hash, and its value will be
+  # `nil`. This is to facilitate easy migration between GC implementations.
+  #
+  # In both call-seqs, the return value of `GC.config` will be a `Hash` containing
+  # the most recent full configuration, i.e., all keys and values defined by the
+  # specific GC implementation being used. In the case of a config update, the
+  # return value will include the new values being updated.
+  #
+  # This method is only expected to work on CRuby.
   #
-  #     GC.config
-  #     # => {rgengc_allow_full_mark: true, implementation: "default"}
+  # ### GC Implementation independent values
   #
-  # With argument `hash_to_merge` given, merges that hash into the stored
-  # configuration hash; ignores unknown hash keys; returns the configuration hash:
+  # The `GC.config` hash can also contain keys that are global and read-only.
+  # These keys are not specific to any one GC library implementation and
+  # attempting to write to them will raise `ArgumentError`.
   #
-  #     GC.config(rgengc_allow_full_mark: false)
-  #     # => {rgengc_allow_full_mark: false, implementation: "default"}
-  #     GC.config(foo: 'bar')
-  #     # => {rgengc_allow_full_mark: false, implementation: "default"}
+  # There is currently only one global, read-only key:
   #
-  # **All-Implementations Configuration**
+  # implementation
+  # :   Returns a `String` containing the name of the currently loaded GC library,
+  #     if one has been loaded using `RUBY_GC_LIBRARY`, and "default" in all other
+  #     cases
   #
-  # The single read-only entry for all implementations is:
   #
-  # *   `:implementation`: the string name of the implementation; for the Ruby
-  #     default implementation, `'default'`.
+  # ### GC Implementation specific values
   #
-  # **Implementation-Specific Configuration**
+  # GC libraries are expected to document their own configuration. Valid keys for
+  # Ruby's default GC implementation are:
   #
-  # A GC implementation maintains its own implementation-specific configuration.
+  # rgengc_allow_full_mark
+  # :   Controls whether the GC is allowed to run a full mark (young & old
+  #     objects).
   #
-  # For Ruby's default implementation the single entry is:
+  #     When `true`, GC interleaves major and minor collections. This is the
+  #     default. GC will function as intended.
   #
-  # *   `:rgengc_allow_full_mark`: Controls whether the GC is allowed to run a
-  #     full mark (young & old objects):
+  #     When `false`, the GC will never trigger a full marking cycle unless
+  #     explicitly requested by user code. Instead, only a minor mark will
+  #     run—only young objects will be marked. When the heap space is exhausted,
+  #     new pages will be allocated immediately instead of running a full mark.
   #
-  #     *   `true` (default): GC interleaves major and minor collections. A flag
-  #         is set to notify GC that a full mark has been requested. This flag is
-  #         accessible via GC.latest_gc_info(:need_major_by).
-  #     *   `false`: GC does not initiate a full marking cycle unless explicitly
-  #         directed by user code; see GC.start. Setting this parameter to `false`
-  #         disables young-to-old promotion. For performance reasons, we
-  #         recommended warming up the application using Process.warmup before
-  #         setting this parameter to `false`.
+  #     A flag will be set to notify that a full mark has been requested. This
+  #     flag is accessible using `GC.latest_gc_info(:needs_major_by)`
+  #
+  #     The user can trigger a major collection at any time using
+  #     `GC.start(full_mark: true)`
+  #
+  #     When `false`, Young to Old object promotion is disabled. For performance
+  #     reasons, it is recommended to warm up an application using
+  #     `Process.warmup` before setting this parameter to `false`.
   #
   def self.config: () -> Hash[Symbol, untyped]
                  | (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - self.count -> integer
+  #   - GC.count -> Integer
   # -->
-  # Returns the total number of times garbage collection has occurred:
-  #
-  #     GC.count # => 385
-  #     GC.start
-  #     GC.count # => 386
+  # Returns the number of times GC has occurred since the process started.
   #
   def self.count: () -> Integer
 
@@ -226,12 +242,11 @@ module GC
   #   rdoc-file=gc.rb
   #   - GC.disable -> true or false
   # -->
-  # Disables garbage collection (but GC.start remains potent): returns whether
-  # garbage collection was already disabled.
+  # Disables garbage collection, returning `true` if garbage collection was
+  # already disabled.
   #
-  #     GC.enable
-  #     GC.disable # => false
-  #     GC.disable # => true
+  #     GC.disable   #=> false
+  #     GC.disable   #=> true
   #
   def self.disable: () -> bool
 
@@ -239,11 +254,12 @@ module GC
   #   rdoc-file=gc.rb
   #   - GC.enable -> true or false
   # -->
-  # Enables garbage collection; returns whether garbage collection was disabled:
+  # Enables garbage collection, returning `true` if garbage collection was
+  # previously disabled.
   #
-  #     GC.disable
-  #     GC.enable # => true
-  #     GC.enable # => false
+  #     GC.disable   #=> false
+  #     GC.enable    #=> true
+  #     GC.enable    #=> false
   #
   def self.enable: () -> bool
 
@@ -251,193 +267,161 @@ module GC
   #   rdoc-file=gc.rb
   #   - start(full_mark: true, immediate_mark: true, immediate_sweep: true)
   # -->
-  # Initiates garbage collection, even if explicitly disabled by GC.disable.
+  # Initiates garbage collection, even if manually disabled.
+  #
+  # The `full_mark` keyword argument determines whether or not to perform a major
+  # garbage collection cycle. When set to `true`, a major garbage collection cycle
+  # is run, meaning all objects are marked. When set to `false`, a minor garbage
+  # collection cycle is run, meaning only young objects are marked.
+  #
+  # The `immediate_mark` keyword argument determines whether or not to perform
+  # incremental marking. When set to `true`, marking is completed during the call
+  # to this method. When set to `false`, marking is performed in steps that are
+  # interleaved with future Ruby code execution, so marking might not be completed
+  # during this method call. Note that if `full_mark` is `false`, then marking
+  # will always be immediate, regardless of the value of `immediate_mark`.
+  #
+  # The `immediate_sweep` keyword argument determines whether or not to defer
+  # sweeping (using lazy sweep). When set to `false`, sweeping is performed in
+  # steps that are interleaved with future Ruby code execution, so sweeping might
+  # not be completed during this method call. When set to `true`, sweeping is
+  # completed during the call to this method.
+  #
+  # Note: These keyword arguments are implementation and version-dependent. They
+  # are not guaranteed to be future-compatible and may be ignored if the
+  # underlying implementation does not support them.
+  #
+  def self.start: (?immediate_sweep: boolish, ?immediate_mark: boolish, ?full_mark: boolish) -> nil
+
+  # <!--
+  #   rdoc-file=gc.rb
+  #   - GC.stat -> Hash
+  #   - GC.stat(hash) -> Hash
+  #   - GC.stat(:key) -> Numeric
+  # -->
+  # Returns a Hash containing information about the GC.
   #
-  # Keyword arguments:
+  # The contents of the hash are implementation-specific and may change in the
+  # future without notice.
   #
-  # *   `full_mark`: its boolean value determines whether to perform a major
-  #     garbage collection cycle:
+  # The hash includes internal statistics about GC such as:
   #
-  #     *   `true`: initiates a major garbage collection cycle, meaning all
-  #         objects (old and new) are marked.
-  #     *   `false`: initiates a minor garbage collection cycle, meaning only
-  #         young objects are marked.
+  # count
+  # :   The total number of garbage collections run since application start (count
+  #     includes both minor and major garbage collections)
   #
-  # *   `immediate_mark`: its boolean value determines whether to perform
-  #     incremental marking:
+  # time
+  # :   The total time spent in garbage collections (in milliseconds)
   #
-  #     *   `true`: marking is completed before the method returns.
-  #     *   `false`: marking is performed by parts, interleaved with program
-  #         execution both before the method returns and afterward; therefore
-  #         marking may not be completed before the return. Note that if
-  #         `full_mark` is `false`, marking will always be immediate, regardless
-  #         of the value of `immediate_mark`.
+  # heap_allocated_pages
+  # :   The total number of `:heap_eden_pages` + `:heap_tomb_pages`
   #
-  # *   `immediate_sweep`: its boolean value determines whether to defer sweeping
-  #     (using lazy sweep):
+  # heap_sorted_length
+  # :   The number of pages that can fit into the buffer that holds references to
+  #     all pages
   #
-  #     *   `true`: sweeping is completed before the method returns.
-  #     *   `false`: sweeping is performed by parts, interleaved with program
-  #         execution both before the method returns and afterward; therefore
-  #         sweeping may not be completed before the return.
+  # heap_allocatable_pages
+  # :   The total number of pages the application could allocate without
+  #     additional GC
   #
-  # Note that these keyword arguments are implementation- and version-dependent,
-  # are not guaranteed to be future-compatible, and may be ignored in some
-  # implementations.
+  # heap_available_slots
+  # :   The total number of slots in all `:heap_allocated_pages`
   #
-  def self.start: (?immediate_sweep: boolish, ?immediate_mark: boolish, ?full_mark: boolish) -> nil
-
-  # <!--
-  #   rdoc-file=gc.rb
-  #   - GC.stat -> new_hash
-  #   - GC.stat(key) -> value
-  #   - GC.stat(hash) -> hash
-  # -->
-  # This method is implementation-specific to CRuby.
-  #
-  # Returns GC statistics. The particular statistics are implementation-specific
-  # and may change in the future without notice.
-  #
-  # With no argument given, returns information about the most recent garbage
-  # collection:
-  #
-  #     GC.stat
-  #     # =>
-  #     {count: 28,
-  #      time: 1,
-  #      marking_time: 1,
-  #      sweeping_time: 0,
-  #      heap_allocated_pages: 521,
-  #      heap_empty_pages: 0,
-  #      heap_allocatable_slots: 0,
-  #      heap_available_slots: 539590,
-  #      heap_live_slots: 422243,
-  #      heap_free_slots: 117347,
-  #      heap_final_slots: 0,
-  #      heap_marked_slots: 264877,
-  #      heap_eden_pages: 521,
-  #      total_allocated_pages: 521,
-  #      total_freed_pages: 0,
-  #      total_allocated_objects: 2246376,
-  #      total_freed_objects: 1824133,
-  #      malloc_increase_bytes: 50982,
-  #      malloc_increase_bytes_limit: 18535172,
-  #      minor_gc_count: 18,
-  #      major_gc_count: 10,
-  #      compact_count: 0,
-  #      read_barrier_faults: 0,
-  #      total_moved_objects: 0,
-  #      remembered_wb_unprotected_objects: 0,
-  #      remembered_wb_unprotected_objects_limit: 2162,
-  #      old_objects: 216365,
-  #      old_objects_limit: 432540,
-  #      oldmalloc_increase_bytes: 1654232,
-  #      oldmalloc_increase_bytes_limit: 16846103}
-  #
-  # With symbol argument `key` given, returns the value for that key:
-  #
-  #     GC.stat(:count) # => 30
-  #
-  # With hash argument `hash` given, returns that hash with GC statistics merged
-  # into its content; this form may be useful in minimizing [probe
-  # effects](https://en.wikipedia.org/wiki/Probe_effect):
-  #
-  #     h = {foo: 0, bar: 1}
-  #     GC.stat(h)
-  #     h.keys.take(5) # => [:foo, :bar, :count, :time, :marking_time]
-  #
-  # The hash includes entries such as:
-  #
-  # *   `:count`: The total number of garbage collections run since application
-  #     start (count includes both minor and major garbage collections).
-  # *   `:time`: The total time spent in garbage collections (in milliseconds).
-  # *   `:heap_allocated_pages`: The total number of allocated pages.
-  # *   `:heap_empty_pages`: The number of pages with no live objects, and that
-  #     could be released to the system.
-  # *   `: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.
-  # *   `: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.
-  # *   `:compact_count`: The total number of compactions run since process start.
-  # *   `:read_barrier_faults`: The total number of times the read barrier was
-  #     triggered during compaction.
-  # *   `:total_moved_objects`: The total number of objects compaction has moved.
-  # *   `: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 `:oldmalloc_increase_bytes`
-  #     crosses this limit, major GC is triggered.
+  # 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
+  #
+  # compact_count
+  # :   The total number of compactions run since process start
+  #
+  # read_barrier_faults
+  # :   The total number of times the read barrier was triggered during compaction
+  #
+  # total_moved_objects
+  # :   The total number of objects compaction has moved
+  #
+  # 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 `:oldmalloc_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 the probe effect.
+  #
+  # This method is only expected to work on CRuby.
   #
   def self.stat: (?Hash[Symbol, untyped]? hash) -> Hash[Symbol, untyped]
                | (Symbol key) -> Integer
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.measure_total_time = setting -> setting
+  #   - GC.measure_total_time = true/false
   # -->
-  # Enables or disables GC total time measurement; returns `setting`. See
-  # GC.total_time.
-  #
-  # When argument `object` is `nil` or `false`, disables total time measurement;
-  # GC.measure_total_time then returns `false`:
-  #
-  #     GC.measure_total_time = nil   # => nil
-  #     GC.measure_total_time         # => false
-  #     GC.measure_total_time = false # => false
-  #     GC.measure_total_time         # => false
-  #
-  # Otherwise, enables total time measurement; GC.measure_total_time then returns
-  # `true`:
-  #
-  #     GC.measure_total_time = true # => true
-  #     GC.measure_total_time        # => true
-  #     GC.measure_total_time = :foo # => :foo
-  #     GC.measure_total_time        # => true
-  #
-  # Note that when enabled, total time measurement affects performance.
+  # Enables measuring GC time. You can get the result with `GC.stat(:time)`. Note
+  # that GC time measurement can cause some performance overhead.
   #
   def self.measure_total_time=: [T] (T enable) -> T
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.measure_total_time -> true or false
+  #   - GC.measure_total_time -> true/false
   # -->
-  # Returns the setting for GC total time measurement; the initial setting is
-  # `true`. See GC.total_time.
+  # Returns the measure_total_time flag (default: `true`). Note that measurement
+  # can affect the application's performance.
   #
   def self.measure_total_time: () -> bool
 
@@ -463,133 +447,71 @@ module GC
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.stat_heap -> new_hash
-  #   - GC.stat_heap(heap_id) -> new_hash
-  #   - GC.stat_heap(heap_id, key) -> value
-  #   - GC.stat_heap(nil, hash) -> hash
-  #   - GC.stat_heap(heap_id, hash) -> hash
+  #   - GC.stat_heap -> Hash
+  #   - GC.stat_heap(nil, hash) -> Hash
+  #   - GC.stat_heap(heap_name) -> Hash
+  #   - GC.stat_heap(heap_name, hash) -> Hash
+  #   - GC.stat_heap(heap_name, :key) -> Numeric
   # -->
-  # This method is implementation-specific to CRuby.
-  #
-  # Returns statistics for GC heaps. The particular statistics are
-  # implementation-specific and may change in the future without notice.
-  #
-  # With no argument given, returns statistics for all heaps:
-  #
-  #     GC.stat_heap
-  #     # =>
-  #     {0 =>
-  #       {slot_size: 40,
-  #        heap_eden_pages: 246,
-  #        heap_eden_slots: 402802,
-  #        total_allocated_pages: 246,
-  #        force_major_gc_count: 2,
-  #        force_incremental_marking_finish_count: 1,
-  #        total_allocated_objects: 33867152,
-  #        total_freed_objects: 33520523},
-  #      1 =>
-  #       {slot_size: 80,
-  #        heap_eden_pages: 84,
-  #        heap_eden_slots: 68746,
-  #        total_allocated_pages: 84,
-  #        force_major_gc_count: 1,
-  #        force_incremental_marking_finish_count: 4,
-  #        total_allocated_objects: 147491,
-  #        total_freed_objects: 90699},
-  #      2 =>
-  #       {slot_size: 160,
-  #        heap_eden_pages: 157,
-  #        heap_eden_slots: 64182,
-  #        total_allocated_pages: 157,
-  #        force_major_gc_count: 0,
-  #        force_incremental_marking_finish_count: 0,
-  #        total_allocated_objects: 211460,
-  #        total_freed_objects: 190075},
-  #      3 =>
-  #       {slot_size: 320,
-  #        heap_eden_pages: 8,
-  #        heap_eden_slots: 1631,
-  #        total_allocated_pages: 8,
-  #        force_major_gc_count: 0,
-  #        force_incremental_marking_finish_count: 0,
-  #        total_allocated_objects: 1422,
-  #        total_freed_objects: 700},
-  #      4 =>
-  #       {slot_size: 640,
-  #        heap_eden_pages: 16,
-  #        heap_eden_slots: 1628,
-  #        total_allocated_pages: 16,
-  #        force_major_gc_count: 0,
-  #        force_incremental_marking_finish_count: 0,
-  #        total_allocated_objects: 1230,
-  #        total_freed_objects: 309}}
-  #
-  # In the example above, the keys in the outer hash are the heap identifiers:
-  #
-  #     GC.stat_heap.keys # => [0, 1, 2, 3, 4]
-  #
-  # On CRuby, each heap identifier is an integer; on other implementations, a heap
-  # identifier may be a string.
-  #
-  # With only argument `heap_id` given, returns statistics for the given heap
-  # identifier:
-  #
-  #     GC.stat_heap(2)
-  #     # =>
-  #     {slot_size: 160,
-  #      heap_eden_pages: 157,
-  #      heap_eden_slots: 64182,
-  #      total_allocated_pages: 157,
-  #      force_major_gc_count: 0,
-  #      force_incremental_marking_finish_count: 0,
-  #      total_allocated_objects: 225018,
-  #      total_freed_objects: 206647}
-  #
-  # With arguments `heap_id` and `key` given, returns the value for the given key
-  # in the given heap:
-  #
-  #     GC.stat_heap(2, :slot_size) # => 160
-  #
-  # With arguments `nil` and `hash` given, merges the statistics for all heaps
-  # into the given hash:
-  #
-  #     h = {foo: 0, bar: 1}
-  #     GC.stat_heap(nil, h).keys # => [:foo, :bar, 0, 1, 2, 3, 4]
-  #
-  # With arguments `heap_id` and `hash` given, merges the statistics for the given
-  # heap into the given hash:
-  #
-  #     h = {foo: 0, bar: 1}
-  #     GC.stat_heap(2, h).keys
-  #     # =>
-  #     [:foo,
-  #      :bar,
-  #      :slot_size,
-  #      :heap_eden_pages,
-  #      :heap_eden_slots,
-  #      :total_allocated_pages,
-  #      :force_major_gc_count,
-  #      :force_incremental_marking_finish_count,
-  #      :total_allocated_objects,
-  #      :total_freed_objects]
-  #
-  # The statistics for a heap may include:
-  #
-  # *   `:slot_size`: The slot size of the heap in bytes.
-  # *   `:heap_allocatable_pages`: The number of pages that can be allocated
-  #     without triggering a new garbage collection cycle.
-  # *   `:heap_eden_pages`: The number of pages in the eden heap.
-  # *   `:heap_eden_slots`: The total number of slots in all of the pages in the
-  #     eden heap.
-  # *   `:total_allocated_pages`: The total number of pages that have been
-  #     allocated in the heap.
-  # *   `:total_freed_pages`: The total number of pages that have been freed and
-  #     released back to the system in the heap.
-  # *   `:force_major_gc_count`: The number of times this heap has forced major
-  #     garbage collection cycles to start due to running out of free slots.
-  # *   `:force_incremental_marking_finish_count`: The number of times this heap
-  #     has forced incremental marking to complete due to running out of pooled
-  #     slots.
+  # Returns information for heaps in the GC.
+  #
+  # If the first optional argument, `heap_name`, is passed in and not `nil`, it
+  # returns a `Hash` containing information about the particular heap. Otherwise,
+  # it will return a `Hash` with heap names as keys and a `Hash` containing
+  # information about the heap as values.
+  #
+  # If the second optional argument, `hash_or_key`, is given as a `Hash`, it will
+  # be overwritten and returned. This is intended to avoid the probe effect.
+  #
+  # If both optional arguments are passed in and the second optional argument is a
+  # symbol, it will return a `Numeric` value for the particular heap.
+  #
+  # On CRuby, `heap_name` is of the type `Integer` but may be of type `String` on
+  # other implementations.
+  #
+  # The contents of the hash are implementation-specific and may change in the
+  # future without notice.
+  #
+  # If the optional argument, hash, is given, it is overwritten and returned.
+  #
+  # This method is only expected to work on CRuby.
+  #
+  # The hash includes the following keys about the internal information in the GC:
+  #
+  # slot_size
+  # :   The slot size of the heap in bytes.
+  #
+  # heap_allocatable_pages
+  # :   The number of pages that can be allocated without triggering a new garbage
+  #     collection cycle.
+  #
+  # heap_eden_pages
+  # :   The number of pages in the eden heap.
+  #
+  # heap_eden_slots
+  # :   The total number of slots in all of the pages in the eden heap.
+  #
+  # heap_tomb_pages
+  # :   The number of pages in the tomb heap. The tomb heap only contains pages
+  #     that do not have any live objects.
+  #
+  # heap_tomb_slots
+  # :   The total number of slots in all of the pages in the tomb heap.
+  #
+  # total_allocated_pages
+  # :   The total number of pages that have been allocated in the heap.
+  #
+  # total_freed_pages
+  # :   The total number of pages that have been freed and released back to the
+  #     system in the heap.
+  #
+  # force_major_gc_count
+  # :   The number of times this heap has forced major garbage collection cycles
+  #     to start due to running out of free slots.
+  #
+  # force_incremental_marking_finish_count
+  # :   The number of times this heap has forced incremental marking to complete
+  #     due to running out of pooled slots.
   #
   def self.stat_heap: (?Integer? heap_name, ?Hash[Symbol, untyped]? hash) -> Hash[Symbol, untyped]
                     | (Integer heap_name, Symbol key) -> Integer
@@ -610,67 +532,37 @@ module GC
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.stress -> setting
+  #   - GC.stress -> integer, true, or false
   # -->
-  # Returns the current GC stress-mode setting, which initially is `false`.
-  #
-  # The stress mode may be set by method GC.stress=.
+  # Returns the current status of GC stress mode.
   #
   def self.stress: () -> (Integer | bool)
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.stress = value -> value
+  #   - GC.stress = flag -> flag
   # -->
-  # Enables or disables stress mode; enabling stress mode will degrade
-  # performance; it is only for debugging.
-  #
-  # Sets the current GC stress mode to the given value:
+  # Updates the GC stress mode.
   #
-  # *   If the value is `nil` or `false`, disables stress mode.
-  # *   If the value is an integer, enables stress mode with certain flags; see
-  #     below.
-  # *   Otherwise, enables stress mode; GC is invoked at every GC opportunity: all
-  #     memory and object allocations.
+  # When stress mode is enabled, the GC is invoked at every GC opportunity: all
+  # memory and object allocations.
   #
-  # The flags are bits in the given integer:
+  # Enabling stress mode will degrade performance; it is only for debugging.
   #
-  # *   `0x01`: No major GC.
-  # *   `0x02`: No immediate sweep.
-  # *   `0x04`: Full mark after malloc/calloc/realloc.
+  # The flag can be true, false, or an integer bitwise-ORed with the following
+  # flags:
+  #     0x01:: no major GC
+  #     0x02:: no immediate sweep
+  #     0x04:: full mark after malloc/calloc/realloc
   #
   def self.stress=: (Integer flag) -> Integer
                   | (bool flag) -> bool
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.total_time -> integer
+  #   - GC.total_time -> int
   # -->
-  # Returns the GC total time in nanoseconds:
-  #
-  #     GC.total_time # => 156250
-  #
-  # Note that total time accumulates only when total time measurement is enabled
-  # (that is, when GC.measure_total_time is `true`):
-  #
-  #     GC.measure_total_time # => true
-  #     GC.total_time # => 625000
-  #     GC.start
-  #     GC.total_time # => 937500
-  #     GC.start
-  #     GC.total_time # => 1093750
-  #
-  #     GC.measure_total_time = false
-  #     GC.total_time # => 1250000
-  #     GC.start
-  #     GC.total_time # => 1250000
-  #     GC.start
-  #     GC.total_time # => 1250000
-  #
-  #     GC.measure_total_time = true
-  #     GC.total_time # => 1250000
-  #     GC.start
-  #     GC.total_time # => 1406250
+  # Returns the measured GC total time in nanoseconds.
   #
   def self.total_time: () -> Integer
 
@@ -727,45 +619,17 @@ module GC
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.latest_gc_info -> new_hash
-  #   - GC.latest_gc_info(key) -> value
+  #   - GC.latest_gc_info -> hash
   #   - GC.latest_gc_info(hash) -> hash
+  #   - GC.latest_gc_info(key) -> value
   # -->
-  # With no argument given, returns information about the most recent garbage
-  # collection:
-  #
-  #     GC.latest_gc_info
-  #     # =>
-  #     {major_by: :force,
-  #      need_major_by: nil,
-  #      gc_by: :method,
-  #      have_finalizer: false,
-  #      immediate_sweep: true,
-  #      state: :none,
-  #      weak_references_count: 0,
-  #      retained_weak_references_count: 0}
-  #
-  # With symbol argument `key` given, returns the value for that key:
-  #
-  #     GC.latest_gc_info(:gc_by) # => :newobj
-  #
-  # With hash argument `hash` given, returns that hash with GC information merged
-  # into its content; this form may be useful in minimizing [probe
-  # effects](https://en.wikipedia.org/wiki/Probe_effect):
-  #
-  #     h = {foo: 0, bar: 1}
-  #     GC.latest_gc_info(h)
-  #     # =>
-  #     {foo: 0,
-  #      bar: 1,
-  #      major_by: nil,
-  #      need_major_by: nil,
-  #      gc_by: :newobj,
-  #      have_finalizer: false,
-  #      immediate_sweep: false,
-  #      state: :sweeping,
-  #      weak_references_count: 0,
-  #      retained_weak_references_count: 0}
+  # Returns information about the most recent garbage collection.
+  #
+  # If the argument `hash` is given and is a Hash object, it is overwritten and
+  # returned. This is intended to avoid the probe effect.
+  #
+  # If the argument `key` is given and is a Symbol object, it returns the value
+  # associated with the key. This is equivalent to `GC.latest_gc_info[key]`.
   #
   def self.latest_gc_info: (?Hash[Symbol, untyped]? hash) -> Hash[Symbol, untyped]
                          | (Symbol key) -> untyped