3 # The GC module provides an interface to Ruby's mark and
4 # sweep garbage collection mechanism.
6 # Some of the underlying methods are also available via the ObjectSpace
9 # You may obtain information about the operation of the GC through
15 # ObjectSpace.garbage_collect -> nil
16 # include GC; garbage_collect -> nil
17 # GC.start(full_mark: true, immediate_sweep: true) -> nil
18 # ObjectSpace.garbage_collect(full_mark: true, immediate_sweep: true) -> nil
19 # include GC; garbage_collect(full_mark: true, immediate_sweep: true) -> nil
21 # Initiates garbage collection, even if manually disabled.
23 # This method is defined with keyword arguments that default to true:
25 # def GC.start(full_mark: true, immediate_sweep: true); end
27 # Use full_mark: false to perform a minor GC.
28 # Use immediate_sweep: false to defer sweeping (use lazy sweep).
30 # Note: These keyword arguments are implementation and version dependent. They
31 # are not guaranteed to be future-compatible, and may be ignored if the
32 # underlying implementation does not support them.
33 def self.start full_mark: true, immediate_mark: true, immediate_sweep: true
34 Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
37 def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
38 Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
42 # GC.auto_compact -> true or false
44 # Returns whether or not automatic compaction has been enabled.
47 Primitive.gc_get_auto_compact
51 # GC.auto_compact = flag
53 # Updates automatic compaction mode.
55 # When enabled, the compactor will execute on every major collection.
57 # Enabling compaction will degrade performance on major collections.
58 def self.auto_compact=(flag)
59 Primitive.gc_set_auto_compact(flag)
63 # GC.enable -> true or false
65 # Enables garbage collection, returning +true+ if garbage
66 # collection was previously disabled.
68 # GC.disable #=> false
77 # GC.disable -> true or false
79 # Disables garbage collection, returning +true+ if garbage
80 # collection was already disabled.
82 # GC.disable #=> false
89 # GC.stress -> integer, true or false
91 # Returns current status of GC stress mode.
93 Primitive.gc_stress_get
97 # GC.stress = flag -> flag
99 # Updates the GC stress mode.
101 # When stress mode is enabled, the GC is invoked at every GC opportunity:
102 # all memory and object allocations.
104 # Enabling stress mode will degrade performance, it is only for debugging.
106 # flag can be true, false, or an integer bit-ORed following flags.
108 # 0x02:: no immediate sweep
109 # 0x04:: full mark after malloc/calloc/realloc
110 def self.stress=(flag)
111 Primitive.gc_stress_set_m flag
115 # GC.count -> Integer
117 # The number of times GC occurred.
119 # It returns the number of times GC occurred since the process started.
126 # GC.stat(hash) -> Hash
127 # GC.stat(:key) -> Numeric
129 # Returns a Hash containing information about the GC.
131 # The contents of the hash are implementation specific and may change in
132 # the future without notice.
134 # The hash includes information about internal statistics about GC such as:
137 # The total number of garbage collections ran since application start
138 # (count includes both minor and major garbage collections)
140 # The total time spent in garbage collections (in milliseconds)
141 # [heap_allocated_pages]
142 # The total number of `:heap_eden_pages` + `:heap_tomb_pages`
143 # [heap_sorted_length]
144 # The number of pages that can fit into the buffer that holds references to
146 # [heap_allocatable_pages]
147 # The total number of pages the application could allocate without additional GC
148 # [heap_available_slots]
149 # The total number of slots in all `:heap_allocated_pages`
151 # The total number of slots which contain live objects
153 # The total number of slots which do not contain live objects
155 # The total number of slots with pending finalizers to be run
156 # [heap_marked_slots]
157 # The total number of objects marked in the last GC
159 # The total number of pages which contain at least one live slot
161 # The total number of pages which do not contain any live slots
162 # [total_allocated_pages]
163 # The cumulative number of pages allocated since application start
164 # [total_freed_pages]
165 # The cumulative number of pages freed since application start
166 # [total_allocated_objects]
167 # The cumulative number of objects allocated since application start
168 # [total_freed_objects]
169 # The cumulative number of objects freed since application start
170 # [malloc_increase_bytes]
171 # Amount of memory allocated on the heap for objects. Decreased by any GC
172 # [malloc_increase_bytes_limit]
173 # When `:malloc_increase_bytes` crosses this limit, GC is triggered
175 # The total number of minor garbage collections run since process start
177 # The total number of major garbage collections run since process start
179 # The total number of compactions run since process start
180 # [read_barrier_faults]
181 # The total number of times the read barrier was triggered during
183 # [total_moved_objects]
184 # The total number of objects compaction has moved
185 # [remembered_wb_unprotected_objects]
186 # The total number of objects without write barriers
187 # [remembered_wb_unprotected_objects_limit]
188 # When `:remembered_wb_unprotected_objects` crosses this limit,
189 # major GC is triggered
191 # Number of live, old objects which have survived at least 3 garbage collections
192 # [old_objects_limit]
193 # When `:old_objects` crosses this limit, major GC is triggered
194 # [oldmalloc_increase_bytes]
195 # Amount of memory allocated on the heap for objects. Decreased by major GC
196 # [oldmalloc_increase_bytes_limit]
197 # When `:old_malloc_increase_bytes` crosses this limit, major GC is triggered
199 # If the optional argument, hash, is given,
200 # it is overwritten and returned.
201 # This is intended to avoid probe effect.
203 # This method is only expected to work on CRuby.
204 def self.stat hash_or_key = nil
205 Primitive.gc_stat hash_or_key
209 # GC.latest_gc_info -> {:gc_by=>:newobj}
210 # GC.latest_gc_info(hash) -> hash
211 # GC.latest_gc_info(:major_by) -> :malloc
213 # Returns information about the most recent garbage collection.
215 # If the optional argument, hash, is given,
216 # it is overwritten and returned.
217 # This is intended to avoid probe effect.
218 def self.latest_gc_info hash_or_key = nil
219 Primitive.gc_latest_gc_info hash_or_key
223 # GC.latest_compact_info -> {:considered=>{:T_CLASS=>11}, :moved=>{:T_CLASS=>11}}
225 # Returns information about object moved in the most recent GC compaction.
227 # The returned hash has two keys :considered and :moved. The hash for
228 # :considered lists the number of objects that were considered for movement
229 # by the compactor, and the :moved hash lists the number of objects that
230 # were actually moved. Some objects can't be moved (maybe they were pinned)
231 # so these numbers can be used to calculate compaction efficiency.
232 def self.latest_compact_info
233 Primitive.gc_compact_stats
239 # This function compacts objects together in Ruby's heap. It eliminates
240 # unused space (or fragmentation) in the heap by moving objects in to that
241 # unused space. This function returns a hash which contains statistics about
242 # which objects were moved. See `GC.latest_gc_info` for details about
243 # compaction statistics.
245 # This method is implementation specific and not expected to be implemented
246 # in any implementation besides MRI.
252 # GC.verify_compaction_references(toward: nil, double_heap: false) -> hash
254 # Verify compaction reference consistency.
256 # This method is implementation specific. During compaction, objects that
257 # were moved are replaced with T_MOVED objects. No object should have a
258 # reference to a T_MOVED object after compaction.
260 # This function doubles the heap to ensure room to move all objects,
261 # compacts the heap to make sure everything moves, updates all references,
262 # then performs a full GC. If any object contains a reference to a T_MOVED
263 # object, that object should be pushed on the mark stack, and will
265 def self.verify_compaction_references(toward: nil, double_heap: false)
266 Primitive.gc_verify_compaction_references(double_heap, toward == :empty)
270 # GC.using_rvargc? -> true or false
272 # Returns true if using experimental feature Variable Width Allocation, false
274 def self.using_rvargc? # :nodoc:
275 GC::INTERNAL_CONSTANTS[:SIZE_POOL_COUNT] > 1
280 # GC.measure_total_time = true/false
282 # Enable to measure GC time.
283 # You can get the result with <tt>GC.stat(:time)</tt>.
284 # Note that GC time measurement can cause some performance overhead.
285 def self.measure_total_time=(flag)
287 rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE;
293 # GC.measure_total_time -> true/false
295 # Return measure_total_time flag (default: +true+).
296 # Note that measurement can affect the application performance.
297 def self.measure_total_time
299 RBOOL(rb_objspace.flags.measure_gc)
304 # GC.total_time -> int
306 # Return measured GC total time in nano seconds.
309 ULL2NUM(rb_objspace.profile.total_time_ns)
315 def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
316 Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
319 module_function :garbage_collect