diff options
Diffstat (limited to 'gc.rb')
| -rw-r--r-- | gc.rb | 154 |
1 files changed, 90 insertions, 64 deletions
@@ -1,39 +1,45 @@ # 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. # # Some of the underlying methods are also available via the ObjectSpace # 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. module GC - # call-seq: - # GC.start -> nil - # ObjectSpace.garbage_collect -> nil - # include GC; garbage_collect -> nil - # GC.start(full_mark: true, immediate_sweep: true) -> nil - # ObjectSpace.garbage_collect(full_mark: true, immediate_sweep: true) -> nil - # include GC; garbage_collect(full_mark: true, immediate_sweep: true) -> nil - # - # Initiates garbage collection, even if manually disabled. - # - # This method is defined with keyword arguments that default to true: - # - # def GC.start(full_mark: true, immediate_sweep: true); end - # - # Use full_mark: false to perform a minor GC. - # Use immediate_sweep: false to defer sweeping (use lazy sweep). - # - # 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. + # 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 ran, meaning all objects are marked. When set to + # +false+, a minor garbage collection cycle is ran, 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 is 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 is 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 full_mark: true, immediate_mark: true, immediate_sweep: true Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false end + # Alias of GC.start def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false end @@ -67,7 +73,7 @@ module GC # call-seq: # GC.stress -> integer, true or false # - # Returns current status of GC stress mode. + # Returns current status of \GC stress mode. def self.stress Primitive.gc_stress_get end @@ -75,9 +81,9 @@ module GC # call-seq: # 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. # # Enabling stress mode will degrade performance, it is only for debugging. @@ -93,9 +99,9 @@ module GC # call-seq: # GC.count -> Integer # - # The number of times GC occurred. + # The number of times \GC occurred. # - # It returns the number of times GC occurred since the process started. + # It returns the number of times \GC occurred since the process started. def self.count Primitive.gc_count end @@ -105,12 +111,12 @@ module GC # GC.stat(hash) -> Hash # 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 future without notice. # - # The hash includes information about internal statistics about GC such as: + # The hash includes information about internal statistics about \GC such as: # # [count] # The total number of garbage collections ran since application start @@ -118,14 +124,14 @@ module GC # [time] # The total time spent in garbage collections (in milliseconds) # [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] # 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 + # 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` + # 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] @@ -133,7 +139,7 @@ module GC # [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 + # 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] @@ -147,9 +153,9 @@ module GC # [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 + # 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 + # 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] @@ -164,16 +170,16 @@ module GC # [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 + # 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 + # 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 + # 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 + # When +:old_malloc_increase_bytes+ crosses this limit, major \GC is triggered # # If the optional argument, hash, is given, # it is overwritten and returned. @@ -191,19 +197,18 @@ module GC # GC.stat_heap(heap_name, hash) -> Hash # GC.stat_heap(heap_name, :key) -> Numeric # - # Returns information for memory pools in the GC. + # 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 memory pool. - # Otherwise, it will return a +Hash+ with memory pool names as keys and - # a +Hash+ containing information about the memory pool as values. + # 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 +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+ of the value for the particular memory - # pool. + # a symbol, it will return a +Numeric+ of the value for the particular heap. # # On CRuby, +heap_name+ is of the type +Integer+ but may be of type +String+ # on other implementations. @@ -214,16 +219,46 @@ module GC # 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 major garbage collection cycles this heap has forced + # 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 heap_name = nil, hash_or_key = nil Primitive.gc_stat_heap heap_name, hash_or_key end - # call-seq: - # GC.latest_gc_info -> {:gc_by=>:newobj} + # call-seq: + # GC.latest_gc_info -> hash # GC.latest_gc_info(hash) -> hash # GC.latest_gc_info(:major_by) -> :malloc # - # Returns information about the most recent garbage collection. + # Returns information about the most recent garbage collection. # # If the optional argument, hash, is given, # it is overwritten and returned. @@ -244,7 +279,7 @@ module GC # # This function expands the heap to ensure room to move all objects, # compacts the heap to make sure everything moves, updates all references, - # then performs a full GC. If any object contains a reference to a T_MOVED + # then performs a full \GC. If any object contains a reference to a T_MOVED # object, that object should be pushed on the mark stack, and will # make a SEGV. def self.verify_compaction_references(toward: nil, double_heap: false, expand_heap: false) @@ -253,21 +288,11 @@ module GC end # call-seq: - # GC.using_rvargc? -> true or false - # - # Returns true if using experimental feature Variable Width Allocation, false - # otherwise. - def self.using_rvargc? # :nodoc: - GC::INTERNAL_CONSTANTS[:SIZE_POOL_COUNT] > 1 - end - - - # call-seq: # GC.measure_total_time = true/false # - # Enable to measure GC time. + # Enable to measure \GC time. # 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) Primitive.cstmt! %{ rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE; @@ -289,15 +314,16 @@ module GC # call-seq: # GC.total_time -> int # - # Return measured GC total time in nano seconds. + # Return measured \GC total time in nano seconds. def self.total_time Primitive.cexpr! %{ - ULL2NUM(rb_objspace.profile.total_time_ns) + ULL2NUM(rb_objspace.profile.marking_time_ns + rb_objspace.profile.sweeping_time_ns) } end end module ObjectSpace + # Alias of GC.start def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false end |