1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix grammar errors and typos in gc.rb

Browse Source
This commit is contained in:
Stan Lo 2024-11-15 14:27:48 -06:00 committed by Peter Zhu
parent 07bf784066
commit 4a7ac694e5
Notes: git 2024-11-18 15:05:10 +00:00 
Merged: https://github.com/ruby/ruby/pull/12102
1 changed files with 131 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
gc.rb
View File

@ -1,39 +1,36 @@
# for gc.c # for gc.c
# The \GC module provides an interface to Ruby's mark and # The \GC module provides an interface to Ruby's mark-and-sweep garbage collection mechanism.
# sweep garbage collection mechanism.
# #
# Some of the underlying methods are also available via the ObjectSpace # Some of the underlying methods are also available via the ObjectSpace module.
# module.
# #
# You may obtain information about the operation of the \GC through # You may obtain information about the operation of the \GC through GC::Profiler.
# GC::Profiler.
module GC module GC
# Initiates garbage collection, even if manually disabled. # Initiates garbage collection, even if manually disabled.
# #
# The +full_mark+ keyword argument determines whether or not to perform a # The +full_mark+ keyword argument determines whether or not to perform a
# major garbage collection cycle. When set to +true+, a major garbage # major garbage collection cycle. When set to +true+, a major garbage
# collection cycle is ran, meaning all objects are marked. When set to # collection cycle is run, meaning all objects are marked. When set to
# +false+, a minor garbage collection cycle is ran, meaning only young # +false+, a minor garbage collection cycle is run, meaning only young
# objects are marked. # objects are marked.
# #
# The +immediate_mark+ keyword argument determines whether or not to perform # The +immediate_mark+ keyword argument determines whether or not to perform
# incremental marking. When set to +true+, marking is completed during the # incremental marking. When set to +true+, marking is completed during the
# call to this method. When set to +false+, marking is performed in steps # call to this method. When set to +false+, marking is performed in steps
# that is interleaved with future Ruby code execution, so marking might not # 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+ # be completed during this method call. Note that if +full_mark+ is +false+,
# then marking will always be immediate, regardless of the value of # then marking will always be immediate, regardless of the value of
# +immediate_mark+. # +immediate_mark+.
# #
# The +immediate_sweep+ keyword argument determines whether or not to defer # The +immediate_sweep+ keyword argument determines whether or not to defer
# sweeping (using lazy sweep). When set to +false+, sweeping is performed in # sweeping (using lazy sweep). When set to +false+, sweeping is performed in
# steps that is interleaved with future Ruby code execution, so sweeping might # 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 # not be completed during this method call. When set to +true+, sweeping is
# completed during the call to this method. # completed during the call to this method.
# #
# Note: These keyword arguments are implementation and version dependent. They # Note: These keyword arguments are implementation and version-dependent. They
# are not guaranteed to be future-compatible, and may be ignored if the # are not guaranteed to be future-compatible and may be ignored if the
# underlying implementation does not support them. # underlying implementation does not support them.
def self.start full_mark: true, immediate_mark: true, immediate_sweep: true def self.start full_mark: true, immediate_mark: true, immediate_sweep: true
Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
@ -44,148 +41,146 @@ module GC
Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
end end
# call-seq: # call-seq:
# GC.enable -> true or false # GC.enable -> true or false
# #
# Enables garbage collection, returning +true+ if garbage # Enables garbage collection, returning +true+ if garbage
# collection was previously disabled. # collection was previously disabled.
# #
# GC.disable #=> false # GC.disable #=> false
# GC.enable #=> true # GC.enable #=> true
# GC.enable #=> false # GC.enable #=> false
# #
def self.enable def self.enable
Primitive.gc_enable Primitive.gc_enable
end end
# call-seq: # call-seq:
# GC.disable -> true or false # GC.disable -> true or false
# #
# Disables garbage collection, returning +true+ if garbage # Disables garbage collection, returning +true+ if garbage
# collection was already disabled. # collection was already disabled.
# #
# GC.disable #=> false # GC.disable #=> false
# GC.disable #=> true # GC.disable #=> true
def self.disable def self.disable
Primitive.gc_disable Primitive.gc_disable
end end
# call-seq: # call-seq:
# GC.stress -> integer, true or false # GC.stress -> integer, true, or false
# #
# Returns current status of \GC stress mode. # Returns the current status of \GC stress mode.
def self.stress def self.stress
Primitive.gc_stress_get Primitive.gc_stress_get
end end
# call-seq: # call-seq:
# GC.stress = flag -> flag # GC.stress = flag -> flag
# #
# Updates the \GC stress mode. # Updates the \GC stress mode.
# #
# When stress mode is enabled, the \GC is invoked at every \GC opportunity: # When stress mode is enabled, the \GC is invoked at every \GC opportunity:
# all memory and object allocations. # all memory and object allocations.
# #
# Enabling stress mode will degrade performance, it is only for debugging. # Enabling stress mode will degrade performance; it is only for debugging.
# #
# flag can be true, false, or an integer bit-ORed following flags. # The flag can be true, false, or an integer bitwise-ORed with the following flags:
# 0x01:: no major GC # 0x01:: no major GC
# 0x02:: no immediate sweep # 0x02:: no immediate sweep
# 0x04:: full mark after malloc/calloc/realloc # 0x04:: full mark after malloc/calloc/realloc
def self.stress=(flag) def self.stress=(flag)
Primitive.gc_stress_set_m flag Primitive.gc_stress_set_m flag
end end
# call-seq: # call-seq:
# GC.count -> Integer # GC.count -> Integer
# #
# The number of times \GC occurred. # Returns the number of times \GC has occurred since the process started.
#
# It returns the number of times \GC occurred since the process started.
def self.count def self.count
Primitive.gc_count Primitive.gc_count
end end
# call-seq: # call-seq:
# GC.stat -> Hash # GC.stat -> Hash
# GC.stat(hash) -> Hash # GC.stat(hash) -> Hash
# GC.stat(:key) -> Numeric # GC.stat(:key) -> Numeric
# #
# Returns a Hash containing information about the \GC. # Returns a Hash containing information about the \GC.
# #
# The contents of the hash are implementation specific and may change in # The contents of the hash are implementation-specific and may change in
# the future without notice. # the future without notice.
# #
# The hash includes information about internal statistics about \GC such as: # The hash includes internal statistics about \GC such as:
# #
# [count] # [count]
# The total number of garbage collections ran since application start # The total number of garbage collections run since application start
# (count includes both minor and major garbage collections) # (count includes both minor and major garbage collections)
# [time] # [time]
# The total time spent in garbage collections (in milliseconds) # The total time spent in garbage collections (in milliseconds)
# [heap_allocated_pages] # [heap_allocated_pages]
# The total number of +:heap_eden_pages+ + +:heap_tomb_pages+ # The total number of +:heap_eden_pages+ + +:heap_tomb_pages+
# [heap_sorted_length] # [heap_sorted_length]
# The number of pages that can fit into the buffer that holds references to # The number of pages that can fit into the buffer that holds references to
# all pages # all pages
# [heap_allocatable_pages] # [heap_allocatable_pages]
# The total number of pages the application could allocate without additional \GC # The total number of pages the application could allocate without additional \GC
# [heap_available_slots] # [heap_available_slots]
# The total number of slots in all +:heap_allocated_pages+ # The total number of slots in all +:heap_allocated_pages+
# [heap_live_slots] # [heap_live_slots]
# The total number of slots which contain live objects # The total number of slots which contain live objects
# [heap_free_slots] # [heap_free_slots]
# The total number of slots which do not contain live objects # The total number of slots which do not contain live objects
# [heap_final_slots] # [heap_final_slots]
# The total number of slots with pending finalizers to be run # The total number of slots with pending finalizers to be run
# [heap_marked_slots] # [heap_marked_slots]
# The total number of objects marked in the last \GC # The total number of objects marked in the last \GC
# [heap_eden_pages] # [heap_eden_pages]
# The total number of pages which contain at least one live slot # The total number of pages which contain at least one live slot
# [heap_tomb_pages] # [heap_tomb_pages]
# The total number of pages which do not contain any live slots # The total number of pages which do not contain any live slots
# [total_allocated_pages] # [total_allocated_pages]
# The cumulative number of pages allocated since application start # The cumulative number of pages allocated since application start
# [total_freed_pages] # [total_freed_pages]
# The cumulative number of pages freed since application start # The cumulative number of pages freed since application start
# [total_allocated_objects] # [total_allocated_objects]
# The cumulative number of objects allocated since application start # The cumulative number of objects allocated since application start
# [total_freed_objects] # [total_freed_objects]
# The cumulative number of objects freed since application start # The cumulative number of objects freed since application start
# [malloc_increase_bytes] # [malloc_increase_bytes]
# Amount of memory allocated on the heap for objects. Decreased by any \GC # Amount of memory allocated on the heap for objects. Decreased by any \GC
# [malloc_increase_bytes_limit] # [malloc_increase_bytes_limit]
# When +:malloc_increase_bytes+ crosses this limit, \GC is triggered # When +:malloc_increase_bytes+ crosses this limit, \GC is triggered
# [minor_gc_count] # [minor_gc_count]
# The total number of minor garbage collections run since process start # The total number of minor garbage collections run since process start
# [major_gc_count] # [major_gc_count]
# The total number of major garbage collections run since process start # The total number of major garbage collections run since process start
# [compact_count] # [compact_count]
# The total number of compactions run since process start # The total number of compactions run since process start
# [read_barrier_faults] # [read_barrier_faults]
# The total number of times the read barrier was triggered during # The total number of times the read barrier was triggered during
# compaction # compaction
# [total_moved_objects] # [total_moved_objects]
# The total number of objects compaction has moved # The total number of objects compaction has moved
# [remembered_wb_unprotected_objects] # [remembered_wb_unprotected_objects]
# The total number of objects without write barriers # The total number of objects without write barriers
# [remembered_wb_unprotected_objects_limit] # [remembered_wb_unprotected_objects_limit]
# When +:remembered_wb_unprotected_objects+ crosses this limit, # When +:remembered_wb_unprotected_objects+ crosses this limit,
# major \GC is triggered # major \GC is triggered
# [old_objects] # [old_objects]
# Number of live, old objects which have survived at least 3 garbage collections # Number of live, old objects which have survived at least 3 garbage collections
# [old_objects_limit] # [old_objects_limit]
# When +:old_objects+ crosses this limit, major \GC is triggered # When +:old_objects+ crosses this limit, major \GC is triggered
# [oldmalloc_increase_bytes] # [oldmalloc_increase_bytes]
# Amount of memory allocated on the heap for objects. Decreased by major \GC # Amount of memory allocated on the heap for objects. Decreased by major \GC
# [oldmalloc_increase_bytes_limit] # [oldmalloc_increase_bytes_limit]
# When +:old_malloc_increase_bytes+ crosses this limit, major \GC is triggered # When +:oldmalloc_increase_bytes+ crosses this limit, major \GC is triggered
# #
# If the optional argument, hash, is given, # If the optional argument, hash, is given,
# it is overwritten and returned. # it is overwritten and returned.
# This is intended to avoid probe effect. # This is intended to avoid the probe effect.
# #
# This method is only expected to work on CRuby. # This method is only expected to work on CRuby.
def self.stat hash_or_key = nil def self.stat hash_or_key = nil
Primitive.gc_stat hash_or_key Primitive.gc_stat hash_or_key
end end
@ -204,16 +199,16 @@ module GC
# Otherwise, it will return a +Hash+ with heap names as keys and # Otherwise, it will return a +Hash+ with heap names as keys and
# a +Hash+ containing information about the heap as values. # a +Hash+ containing information about the heap as values.
# #
# If the second optional argument, +hash_or_key+, is given as +Hash+, it will # 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. # 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 # If both optional arguments are passed in and the second optional argument is
# a symbol, it will return a +Numeric+ of the value for the particular heap. # 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 CRuby, +heap_name+ is of the type +Integer+ but may be of type +String+
# on other implementations. # on other implementations.
# #
# The contents of the hash are implementation specific and may change in # The contents of the hash are implementation-specific and may change in
# the future without notice. # the future without notice.
# #
# If the optional argument, hash, is given, it is overwritten and returned. # If the optional argument, hash, is given, it is overwritten and returned.
@ -243,7 +238,7 @@ module GC
# The total number of pages that have been freed and released back to the # The total number of pages that have been freed and released back to the
# system in the heap. # system in the heap.
# [force_major_gc_count] # [force_major_gc_count]
# The number of times major garbage collection cycles this heap has forced # The number of times this heap has forced major garbage collection cycles
# to start due to running out of free slots. # to start due to running out of free slots.
# [force_incremental_marking_finish_count] # [force_incremental_marking_finish_count]
# The number of times this heap has forced incremental marking to complete # The number of times this heap has forced incremental marking to complete
@ -259,7 +254,7 @@ module GC
# #
# Sets or gets information about the current \GC config. # Sets or gets information about the current \GC config.
# #
# Configuration parameters are \GC implementation specific and may change # Configuration parameters are \GC implementation-specific and may change
# without notice. # without notice.
# #
# This method can be called without parameters to retrieve the current config. # This method can be called without parameters to retrieve the current config.
@ -270,11 +265,11 @@ module GC
# #
# If a key/value pair is passed to this function that does not correspond to # 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 # 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 # 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. # 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+ # 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 # 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 # 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. # config update, the return value will include the new values being updated.
# #
@ -283,13 +278,13 @@ module GC
# Valid config keys for Ruby's default \GC implementation are: # Valid config keys for Ruby's default \GC implementation are:
# #
# [rgengc_allow_full_mark] # [rgengc_allow_full_mark]
# Control whether the \GC is allowed to run a full mark (young & old objects). # Controls 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 # When +true+, \GC interleaves major and minor collections. This is the default. \GC
# will function as intended. # will function as intended.
# #
# When +false+, the \GC will never trigger a full marking cycle unless # When +false+, the \GC will never trigger a full marking cycle unless
# explicitly requested by user code. Instead only a minor mark will run - # 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 # only young objects will be marked. When the heap space is exhausted, new
# pages will be allocated immediately instead of running a full mark. # pages will be allocated immediately instead of running a full mark.
# #
@ -300,8 +295,8 @@ module GC
# The user can trigger a major collection at any time using # The user can trigger a major collection at any time using
# <code>GC.start(full_mark: true)</code> # <code>GC.start(full_mark: true)</code>
# #
# When +false+. Young to Old object promotion is disabled. For performance # When +false+, Young to Old object promotion is disabled. For performance
# reasons it is recommended to warmup an application using +Process.warmup+ # reasons, it is recommended to warm up an application using +Process.warmup+
# before setting this parameter to +false+. # before setting this parameter to +false+.
def self.config hash = nil def self.config hash = nil
return Primitive.gc_config_get unless hash return Primitive.gc_config_get unless hash
@ -326,7 +321,7 @@ module GC
# #
# If the argument +hash+ is given and is a Hash object, # If the argument +hash+ is given and is a Hash object,
# it is overwritten and returned. # it is overwritten and returned.
# This is intended to avoid probe effect. # This is intended to avoid the probe effect.
# #
# If the argument +key+ is given and is a Symbol object, # If the argument +key+ is given and is a Symbol object,
# it returns the value associated with the key. # it returns the value associated with the key.
@ -346,7 +341,7 @@ module GC
# call-seq: # call-seq:
# GC.measure_total_time = true/false # GC.measure_total_time = true/false
# #
# Enable to measure \GC time. # Enables measuring \GC time.
# You can get the result with <tt>GC.stat(:time)</tt>. # You can get the result with <tt>GC.stat(:time)</tt>.
# Note that \GC time measurement can cause some performance overhead. # Note that \GC time measurement can cause some performance overhead.
def self.measure_total_time=(flag) def self.measure_total_time=(flag)
@ -359,8 +354,8 @@ module GC
# call-seq: # call-seq:
# GC.measure_total_time -> true/false # GC.measure_total_time -> true/false
# #
# Return measure_total_time flag (default: +true+). # Returns the measure_total_time flag (default: +true+).
# Note that measurement can affect the application performance. # Note that measurement can affect the application's performance.
def self.measure_total_time def self.measure_total_time
Primitive.cexpr! %{ Primitive.cexpr! %{
RBOOL(rb_gc_impl_get_measure_total_time(rb_gc_get_objspace())) RBOOL(rb_gc_impl_get_measure_total_time(rb_gc_get_objspace()))
@ -370,7 +365,7 @@ module GC
# call-seq: # call-seq:
# GC.total_time -> int # GC.total_time -> int
# #
# Return measured \GC total time in nano seconds. # Returns the measured \GC total time in nanoseconds.
def self.total_time def self.total_time
Primitive.cexpr! %{ Primitive.cexpr! %{
ULL2NUM(rb_gc_impl_get_total_time(rb_gc_get_objspace())) ULL2NUM(rb_gc_impl_get_total_time(rb_gc_get_objspace()))