core/gc.rbs in rbs-2.0.0 vs core/gc.rbs in rbs-2.1.0

- old
+ new

@@ -1,36 +1,58 @@ +# <!-- rdoc-file=gc.rb --> # 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 GC::Profiler. # module GC + # <!-- + # rdoc-file=gc.rb + # - GC.count -> Integer + # --> # The number of times GC occurred. # # It returns the number of times GC occurred since the process started. # def self.count: () -> Integer + # <!-- + # rdoc-file=gc.rb + # - GC.disable -> true or false + # --> # Disables garbage collection, returning `true` if garbage collection was # already disabled. # # GC.disable #=> false # GC.disable #=> true # def self.disable: () -> bool + # <!-- + # rdoc-file=gc.rb + # - GC.enable -> true or false + # --> # Enables garbage collection, returning `true` if garbage collection was # previously disabled. # # GC.disable #=> false # GC.enable #=> true # GC.enable #=> false # def self.enable: () -> bool + # <!-- + # rdoc-file=gc.rb + # - 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 @@ -42,54 +64,101 @@ # are not guaranteed to be future-compatible, and may be ignored if the # underlying implementation does not support them. # def self.start: (?immediate_sweep: boolish immediate_sweep, ?immediate_mark: boolish immediate_mark, ?full_mark: boolish full_mark) -> nil + # <!-- + # rdoc-file=gc.rb + # - GC.stat -> Hash + # - GC.stat(hash) -> Hash + # - GC.stat(:key) -> Numeric + # --> # 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: # - # { - # :count=>0, - # :heap_allocated_pages=>24, - # :heap_sorted_length=>24, - # :heap_allocatable_pages=>0, - # :heap_available_slots=>9783, - # :heap_live_slots=>7713, - # :heap_free_slots=>2070, - # :heap_final_slots=>0, - # :heap_marked_slots=>0, - # :heap_eden_pages=>24, - # :heap_tomb_pages=>0, - # :total_allocated_pages=>24, - # :total_freed_pages=>0, - # :total_allocated_objects=>7796, - # :total_freed_objects=>83, - # :malloc_increase_bytes=>2389312, - # :malloc_increase_bytes_limit=>16777216, - # :minor_gc_count=>0, - # :major_gc_count=>0, - # :remembered_wb_unprotected_objects=>0, - # :remembered_wb_unprotected_objects_limit=>0, - # :old_objects=>0, - # :old_objects_limit=>0, - # :oldmalloc_increase_bytes=>2389760, - # :oldmalloc_increase_bytes_limit=>16777216 - # } + # count + # : The total number of garbage collections ran since application start (count + # includes both minor and major garbage collections) + # heap_allocated_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 + # heap_available_slots + # : 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 + # : The total number of slots which do not contain live objects + # 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 + # heap_eden_pages + # : The total number of pages which contain at least one live slot + # heap_tomb_pages + # : The total number of pages which do not contain any live slots + # total_allocated_pages + # : The cumulative number of pages allocated since application start + # total_freed_pages + # : The cumulative number of pages freed since application start + # total_allocated_objects + # : The cumulative number of objects allocated since application start + # 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 + # malloc_increase_bytes_limit + # : 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 + # : The total number of major garbage collections run since process start + # 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 + # 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 + # oldmalloc_increase_bytes + # : 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 # - # The contents of the hash are implementation specific and may be changed in the - # future. # - # This method is only expected to work on C Ruby. + # If the optional argument, hash, is given, it is overwritten and returned. This + # is intended to avoid probe effect. # + # This method is only expected to work on CRuby. + # def self.stat: (?::Hash[Symbol, Integer] arg0) -> ::Hash[Symbol, Integer] | (?Symbol arg0) -> Integer + # <!-- + # rdoc-file=gc.rb + # - GC.stress -> integer, true or false + # --> # Returns current status of GC stress mode. # def self.stress: () -> (Integer | TrueClass | FalseClass) + # <!-- + # rdoc-file=gc.rb + # - GC.stress = flag -> flag + # --> # Updates the GC stress mode. # # When stress mode is enabled, the GC is invoked at every GC opportunity: all # memory and object allocations. # @@ -100,12 +169,37 @@ # 0x02:: no immediate sweep # 0x04:: full mark after malloc/calloc/realloc # def self.stress=: (Integer | TrueClass | FalseClass flag) -> (Integer | TrueClass | FalseClass) + # <!-- + # rdoc-file=gc.rb + # - GC.total_time -> int + # --> + # Return measured GC total time in nano seconds. + # + def self.total_time: () -> Integer + + # <!-- + # rdoc-file=gc.rb + # - GC.compact + # --> + # This function compacts objects together in Ruby's heap. It eliminates unused + # space (or fragmentation) in the heap by moving objects in to that unused + # space. This function returns a hash which contains statistics about which + # objects were moved. See `GC.latest_gc_info` for details about compaction + # statistics. + # + # This method is implementation specific and not expected to be implemented in + # any implementation besides MRI. + # def self.compact: () -> ::Hash[:considered | :moved, Hash[Symbol | Integer, Integer]] + # <!-- + # rdoc-file=gc.rb + # - GC.verify_compaction_references(toward: nil, double_heap: false) -> hash + # --> # Verify compaction reference consistency. # # This method is implementation specific. During compaction, objects that were # moved are replaced with T_MOVED objects. No object should have a reference to # a T_MOVED object after compaction. @@ -115,38 +209,62 @@ # 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: () -> ::Hash[:considered | :moved, Hash[Symbol | Integer, Integer]] + # <!-- + # rdoc-file=gc.c + # - GC.verify_internal_consistency -> nil + # --> # Verify internal consistency. # # This method is implementation specific. Now this method checks generational # consistency if RGenGC is supported. # def self.verify_internal_consistency: () -> nil + # <!-- + # rdoc-file=gc.c + # - verify_transient_heap_internal_consistency() + # --> + # def self.verify_transient_heap_internal_consistency: () -> nil + # <!-- + # rdoc-file=gc.rb + # - GC.latest_gc_info -> {:gc_by=>:newobj} + # - GC.latest_gc_info(hash) -> hash + # - GC.latest_gc_info(:major_by) -> :malloc + # --> # Returns information about the most recent garbage collection. # + # If the optional argument, hash, is given, it is overwritten and returned. This + # is intended to avoid probe effect. + # def self.latest_gc_info: () -> ::Hash[::Symbol, untyped] | [K] (?Hash[K, untyped] hash) -> ::Hash[::Symbol | K, untyped] | (Symbol key) -> untyped + # <!-- + # rdoc-file=gc.rb + # - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true) + # --> + # def garbage_collect: (?immediate_sweep: boolish immediate_sweep, ?immediate_mark: boolish immediate_mark, ?full_mark: boolish full_mark) -> nil end +# <!-- rdoc-file=gc.c --> # internal constants # -# GC::INTERNAL_CONSTANTS: Hash[Symbol, Integer] +# <!-- rdoc-file=gc.c --> # GC build options # -# GC::OPTS: Array[String] +# <!-- rdoc-file=gc.c --> # The GC profiler provides access to information on GC runs including time, # length and object space size. # # Example: # @@ -159,26 +277,46 @@ # GC::Profiler.disable # # See also GC.count, GC.malloc_allocated_size and GC.malloc_allocations # module GC::Profiler + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.clear -> nil + # --> # Clears the GC profiler data. # def self.clear: () -> void + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.disable -> nil + # --> # Stops the GC profiler. # def self.disable: () -> void + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.enable -> nil + # --> # Starts the GC profiler. # def self.enable: () -> void + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.enabled? -> true or false + # --> # The current status of GC profile mode. # def self.enabled?: () -> bool + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.raw_data -> [Hash, ...] + # --> # Returns an Array of individual raw profile data Hashes ordered from earliest # to latest by `:GC_INVOKE_TIME`. # # For example: # @@ -223,21 +361,34 @@ # `:HAVE_FINALIZE` # : # def self.raw_data: () -> ::Array[::Hash[Symbol, untyped]] + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.report + # - GC::Profiler.report(io) + # --> # Writes the GC::Profiler.result to `$stdout` or the given IO object. # def self.report: (?IO io) -> void + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.result -> String + # --> # Returns a profile data report such as: # # GC 1 invokes. # Index Invoke Time(sec) Use Size(byte) Total Size(byte) Total Object GC time(ms) # 1 0.012 159240 212940 10647 0.00000000000001530000 # def self.result: () -> String + # <!-- + # rdoc-file=gc.c + # - GC::Profiler.total_time -> float + # --> # The total time used for garbage collection in seconds # def self.total_time: () -> Float end