diff options
Diffstat (limited to 'gc.rb')
| -rw-r--r-- | gc.rb | 92 |
1 files changed, 64 insertions, 28 deletions
@@ -1,6 +1,6 @@ # 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 @@ -10,30 +10,36 @@ # 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 @@ -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,6 +219,36 @@ 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 @@ -282,12 +317,13 @@ module GC # 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 |