Document GC.config

1 files changed, 39 insertions, 7 deletions

diff --git a/gc.rb b/gc.rb
index 836904fe8c..f714fba749 100644
--- a/gc.rb
+++ b/gc.rb
@@ -259,18 +259,50 @@ module GC
   #
   # Sets or gets information about the current GC config.
   #
-  # The contents of the hash are implementation specific and may change in
-  # the future without notice.
+  # Configuration parameters are GC implementation specific and may change
+  # without notice.
   #
-  # If the optional argument, hash, is given, it is overwritten and returned.
+  # This method can be called without parameters to retrieve the current config.
+  #
+  # 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 it's value will
+  # be +nil+. This is to facilitate easy migration between GC implementations.
+  #
+  # In both call-seqs the return value of <code>GC.config</code> will be a +Hash+
+  # containing the most recent full configuration. ie. 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.
   #
-  # The hash includes the following keys about the internal information in
-  # the \GC:
+  # Valid config keys for Ruby's default GC implementation are:
   #
-  # [slot_size]
-  #   The slot size of the heap in bytes.
+  # [rgengc_allow_full_mark]
+  #   Control whether the GC is allowed to run a full mark (young & old objects).
+  #
+  #   When +true+ GC interleaves major and minor collections. This is default. GC
+  #   will function as intended.
+  #
+  #   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.
+  #
+  #   A flag will be set to notify that a full mark has been
+  #   requested. This flag is accessible using
+  #   <code>GC.latest_gc_info(:needs_major_by)</code>
+  #
+  #   The user can trigger a major collection at any time using
+  #   <code>GC.start(full_mark: true)</code>
+  #
+  #   When +false+. Young to Old object promotion is disabled. For performance
+  #   reasons it is recommended to warmup an application using +Process.warmup+
+  #   before setting this parameter to +false+.
   def self.config hash = nil
     return Primitive.gc_config_get unless hash