From a7ec1e16ae2e796fc37edc9a6c69e4007a69bb94 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 6 Aug 2025 17:59:15 -0500 Subject: [PATCH 1/2] [DOC] Tweaks for GC.config --- gc.rb | 85 +++++++++++++++++++++++++---------------------------------- 1 file changed, 36 insertions(+), 49 deletions(-) diff --git a/gc.rb b/gc.rb index d3bb8db036b1cb..71c565faf1c743 100644 --- a/gc.rb +++ b/gc.rb @@ -250,71 +250,58 @@ def self.stat_heap heap_name = nil, hash_or_key = nil # call-seq: # GC.config -> hash - # GC.config(hash) -> hash + # GC.config(hash_to_merge) -> merged_hash # - # Sets or gets information about the current \GC config. + # This method is expected to be defined, useful, and well-behaved + # only in the CRuby implementation. # - # Configuration parameters are \GC implementation-specific and may change - # without notice. + # Sets or gets information about the current \GC configuration. # - # This method can be called without parameters to retrieve the current config - # as a +Hash+ with +Symbol+ keys. + # With no argument given, returns a hash containing the configuration: # - # 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. + # GC.config + # # => {rgengc_allow_full_mark: true, implementation: "default"} # - # 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. + # With argument +hash_to_merge+ given, + # merges that hash into the stored configuration hash; + # ignores unknown hash keys; + # returns the implementation-specific configuration hash (see below): # - # 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. + # GC.config(rgengc_allow_full_mark: false) + # # => {rgengc_allow_full_mark: false} + # GC.config + # # => {rgengc_allow_full_mark: false, implementation: "default"} + # GC.config(foo: 'bar') + # # => {rgengc_allow_full_mark: false} + # GC.config + # # => {rgengc_allow_full_mark: false, implementation: "default"} # - # This method is only expected to work on CRuby. - # - # === \GC Implementation independent values - # - # 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+. + # All-Implementations Configuration # - # There is currently only one global, read-only key: + # The single read-only entry for all implementations is: # - # [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 + # - +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. + # - +false+: \GC does not initiate a full marking cycle unless + # explicitly directed by user code; + # see GC.start. # - # A flag will be set to notify that a full mark has been - # requested. This flag is accessible using - # GC.latest_gc_info(:need_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+ + # 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+. + # def self.config hash = nil return Primitive.gc_config_get unless hash From feaa4167fef9abca04bf89dd76a546a024998bc9 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 8 Aug 2025 11:19:40 -0500 Subject: [PATCH 2/2] [DOC] Tweaks for GC.config --- gc.rb | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/gc.rb b/gc.rb index 71c565faf1c743..c53fc2e5487cef 100644 --- a/gc.rb +++ b/gc.rb @@ -252,11 +252,12 @@ def self.stat_heap heap_name = nil, hash_or_key = nil # GC.config -> hash # GC.config(hash_to_merge) -> merged_hash # - # This method is expected to be defined, useful, and well-behaved - # only in the CRuby implementation. + # This method is implementation-specific to CRuby. # # Sets or gets information about the current \GC configuration. # + # Configuration parameters are \GC implementation-specific and may change without notice. + # # With no argument given, returns a hash containing the configuration: # # GC.config @@ -294,13 +295,13 @@ def self.stat_heap heap_name = nil, hash_or_key = nil # Controls whether the \GC is allowed to run a full mark (young & old objects): # # - +true+ (default): \GC interleaves major and minor collections. - # - +false+: \GC does not initiate a full marking cycle unless - # explicitly directed by user code; + # 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+. + # 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+. # def self.config hash = nil return Primitive.gc_config_get unless hash