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)
139 # [heap_allocated_pages]
140 # The total number of `:heap_eden_pages` + `:heap_tomb_pages`
141 # [heap_sorted_length]
142 # The number of pages that can fit into the buffer that holds references to
144 # [heap_allocatable_pages]
145 # The total number of pages the application could allocate without additional GC
146 # [heap_available_slots]
147 # The total number of slots in all `:heap_allocated_pages`
149 # The total number of slots which contain live objects
151 # The total number of slots which do not contain live objects
153 # The total number of slots with pending finalizers to be run
154 # [heap_marked_slots]
155 # The total number of objects marked in the last GC
157 # The total number of pages which contain at least one live slot
159 # The total number of pages which do not contain any live slots
160 # [total_allocated_pages]
161 # The cumulative number of pages allocated since application start
162 # [total_freed_pages]
163 # The cumulative number of pages freed since application start
164 # [total_allocated_objects]
165 # The cumulative number of objects allocated since application start
166 # [total_freed_objects]
167 # The cumulative number of objects freed since application start
168 # [malloc_increase_bytes]
169 # Amount of memory allocated on the heap for objects. Decreased by any GC
170 # [malloc_increase_bytes_limit]
171 # When `:malloc_increase_bytes` crosses this limit, GC is triggered
173 # The total number of minor garbage collections run since process start
175 # The total number of major garbage collections run since process start
176 # [remembered_wb_unprotected_objects]
177 # The total number of objects without write barriers
178 # [remembered_wb_unprotected_objects_limit]
179 # When `:remembered_wb_unprotected_objects` crosses this limit,
180 # major GC is triggered
182 # Number of live, old objects which have survived at least 3 garbage collections
183 # [old_objects_limit]
184 # When `:old_objects` crosses this limit, major GC is triggered
185 # [oldmalloc_increase_bytes]
186 # Amount of memory allocated on the heap for objects. Decreased by major GC
187 # [oldmalloc_increase_bytes_limit]
188 # When `:old_malloc_increase_bytes` crosses this limit, major GC is triggered
190 # If the optional argument, hash, is given,
191 # it is overwritten and returned.
192 # This is intended to avoid probe effect.
194 # This method is only expected to work on CRuby.
195 def self.stat hash_or_key = nil
196 Primitive.gc_stat hash_or_key
200 # GC.latest_gc_info -> {:gc_by=>:newobj}
201 # GC.latest_gc_info(hash) -> hash
202 # GC.latest_gc_info(:major_by) -> :malloc
204 # Returns information about the most recent garbage collection.
206 # If the optional argument, hash, is given,
207 # it is overwritten and returned.
208 # This is intended to avoid probe effect.
209 def self.latest_gc_info hash_or_key = nil
210 Primitive.gc_latest_gc_info hash_or_key
214 # GC.latest_compact_info -> {:considered=>{:T_CLASS=>11}, :moved=>{:T_CLASS=>11}}
216 # Returns information about object moved in the most recent GC compaction.
218 # The returned hash has two keys :considered and :moved. The hash for
219 # :considered lists the number of objects that were considered for movement
220 # by the compactor, and the :moved hash lists the number of objects that
221 # were actually moved. Some objects can't be moved (maybe they were pinned)
222 # so these numbers can be used to calculate compaction efficiency.
223 def self.latest_compact_info
224 Primitive.gc_compact_stats
230 # This function compacts objects together in Ruby's heap. It eliminates
231 # unused space (or fragmentation) in the heap by moving objects in to that
232 # unused space. This function returns a hash which contains statistics about
233 # which objects were moved. See `GC.latest_gc_info` for details about
234 # compaction statistics.
236 # This method is implementation specific and not expected to be implemented
237 # in any implementation besides MRI.
243 # GC.verify_compaction_references(toward: nil, double_heap: false) -> hash
245 # Verify compaction reference consistency.
247 # This method is implementation specific. During compaction, objects that
248 # were moved are replaced with T_MOVED objects. No object should have a
249 # reference to a T_MOVED object after compaction.
251 # This function doubles the heap to ensure room to move all objects,
252 # compacts the heap to make sure everything moves, updates all references,
253 # then performs a full GC. If any object contains a reference to a T_MOVED
254 # object, that object should be pushed on the mark stack, and will
256 def self.verify_compaction_references(toward: nil, double_heap: false)
257 Primitive.gc_verify_compaction_references(double_heap, toward == :empty)
261 # GC.using_rvargc? -> true or false
263 # Returns true if using experimental feature Variable Width Allocation, false
265 def self.using_rvargc? # :nodoc:
266 GC::INTERNAL_CONSTANTS[:SIZE_POOL_COUNT] > 1
271 # GC.measure_total_time = true/false
273 # Enable to measure GC time.
274 # You can get the result with <tt>GC.stat(:time)</tt>.
275 # Note that GC time measurement can cause some performance overhead.
276 def self.measure_total_time=(flag)
278 rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE;
284 # GC.measure_total_time -> true/false
286 # Return measure_total_time flag (default: +true+).
287 # Note that measurement can affect the application performance.
288 def self.measure_total_time
290 RBOOL(rb_objspace.flags.measure_gc)
295 # GC.total_time -> int
297 # Return measured GC total time in nano seconds.
300 ULL2NUM(rb_objspace.profile.total_time_ns)
306 def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
307 Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
310 module_function :garbage_collect