Garbage Collection and Memory

An object lives in a slot: a fixed-size cell on a heap page. When the program creates an object, the allocator takes a free slot from a page; when no slot is free, or when memory obtained through malloc grows past a limit, the collector runs. CRuby uses a tracing collector, described in the GC documentation as a mark-and-sweep mechanism: it starts from the roots (global variables, constants, the VM stacks of every thread and Fiber, and the machine stack), marks every object it can reach, and sweeps the pages to turn the unmarked slots back into free slots. Sweeping is lazy by default: a page is swept when the allocator needs its slots, and GC.start(immediate_sweep: false) leaves sweeping unfinished on purpose. Around that core, CRuby adds several refinements that matter when you read GC.stat:

The refinements, and the release that introduced each (all from the release notes linked in the references):

The rest of the page takes the pieces in this order: the heap layout, measuring, generations, controlling the collector, compaction, tuning, the modular GC, ObjectSpace, weak references and finally the practical business of reducing memory use.

A heap page is 64 KiB. The standard slot size is 40 bytes on a 64-bit platform, and since Variable Width Allocation there are five size pools whose slots are 40, 80, 160, 320 and 640 bytes. A new object goes to the smallest pool whose slots can hold it together with the payload it can embed. What does not fit (a long string, a large array, a hash table, the data of a C extension) is allocated with malloc outside the heap and referenced from the slot. ObjectSpace.memsize_of (library objspace) returns the slot size plus that external memory.

Source: ObjectSpace.memsize_of and GC.stat_heap

Things to take from the example:

GC.count is the number of collections since the process started. GC.stat returns a hash of counters, GC.stat(key) returns one value (without building the hash, which matters when the measurement itself should not allocate), and GC.stat(hash) fills a hash you pass in. The entries the documentation describes are:

The documentation also warns that the entries are implementation-specific and "may change in the future without notice"; the set of keys in 4.0.7 differs from the sample in the reference (the descriptions still list heap_allocatable_pages and heap_sorted_length, while 4.0.7 returns heap_allocatable_slots instead). Print GC.stat.keys before depending on a name. GC.stat_heap gives the per-size-pool view (slot_size, heap_eden_pages, heap_eden_slots, total_allocated_objects and so on, with force_major_gc_count counting the major collections that one pool forced by running out of slots), and GC.latest_gc_info describes the most recent collection: why it ran (gc_by: :newobj, :malloc, :method, :stress), whether it was major and why (major_by), whether a major one is already pending (need_major_by), whether sweeping was immediate, the current state (:none, :marking, :sweeping) and the weak-reference counters.

Source: GC.stat

The program built 5000 books and the collector ran 36 times while it did so, 32 minor and 4 major; most of the 370,000 objects were short-lived (the ISBN check digit helper allocates strings and arrays for every book) and were freed again, so a book costs far fewer live objects than allocations. Two habits make such numbers useful:

GC.measure_total_time (3.1) controls whether the collector measures its own time; it is on by default, and the documentation notes that measuring has a cost. GC.total_time returns the accumulated time in nanoseconds, while the time entry of GC.stat is in milliseconds. A service can export GC.stat(:count), GC.stat(:time) and GC.stat(:heap_live_slots) to its metrics system to see collector pressure over time.

Most objects die young. A minor collection exploits that by marking only the young objects, plus the remembered set (the old objects that were changed to point at young ones), and assumes that every old object is still alive. An object becomes old after surviving three collections (the old_objects entry of GC.stat is documented as objects that "have survived at least 3 garbage collections"). A major collection marks every object and is the only one that can reclaim old garbage.

To keep minor collections correct the collector needs to know when an old object is made to point at a young one. That is the write barrier: assignments to instance variables, array and hash elements and so on go through a barrier that records the old object in the remembered set. Objects of a type that does not implement the barrier are called write-barrier unprotected (wb_unprotected); they can never be treated as old, which makes minor collections more expensive, and the remembered_wb_unprotected_objects_limit entry shows the count at which a major collection is forced. This is why the 3.3 and 4.0 release notes list write barriers added to core classes as a performance improvement, and why a C extension that stores references without the barrier macros costs the whole process collector time (see C Extensions, FFI and WebAssembly).

A major collection is triggered when one of the limits shown in GC.stat is crossed (old_objects_limit, oldmalloc_increase_bytes_limit, remembered_wb_unprotected_objects_limit), when a heap runs out of free slots (force_major_gc_count), or when the program calls GC.start. GC.latest_gc_info(:major_by) records the reason and :need_major_by records a major collection that has been requested but not yet run. ObjectSpace.dump (library objspace, JSON text) shows the age and flags of one object, which makes the machinery visible:

Source: ObjectSpace.dump and GC.latest_gc_info

The array is created young (age 0), is promoted to old by the second explicit minor collection and then stays old. The exact age after the first collection depends on how many automatic collections ran in between (here one did, because building the strings and parsing the JSON allocate), so the progression 0, then 2, then 3 is not something to rely on; what matters is that a handful of collections turns a surviving object into an old one. GC.start(full_mark: false) is a minor collection (major_by stays nil), and plain GC.start is a forced major one (major_by: :force).

GC.config (3.4) reads and changes collector settings. The only entry of the default implementation is rgengc_allow_full_mark. Setting it to false stops the collector from starting major collections on its own, which also disables promotion to the old generation; the documentation recommends calling Process.warmup before doing it. It is a setting for processes with a short, bounded life or an external restart policy, not a general tuning knob.

Source: GC.config

The second p shows the merged configuration after the change, the third shows that an unknown key is silently ignored, and the read-only implementation entry cannot be changed (the message is shown capitalised exactly as Ruby prints it).

GC.start runs a collection even if collection is disabled. Its keyword arguments, documented as implementation- and version-dependent, select the kind and how much work is deferred:

Source: GC.start, GC.disable and https://docs.ruby-lang.org/en/4.0/GC.html#method-c-stress-3D

Two million objects were allocated with collection disabled and no collection ran, which is exactly the danger of GC.disable: the process’s memory grows until someone calls GC.enable or the machine runs out. The partial collection of the example returns while sweeping is still in progress (state: :sweeping), which is what immediate_sweep: false asks for. Under GC.stress even 20 small allocations triggered 26 collections; the mode exists to shake out bugs in C extensions that forget to protect an object from the collector.

Guidelines for calling the collector yourself:

Long-running processes fragment the heap: after many objects die, free slots are scattered over many pages, and a page with a single live object cannot be released. Compaction moves live objects next to each other and updates every reference to them, so that pages become empty and can be given back. GC.compact (2.7) does it on demand, and GC.auto_compact = true (3.0) compacts during major collections. Neither is described on the 4.0 reference pages for GC, so the release notes are the place to look (and ri has no entry for them either); the methods are GC.compact, GC.auto_compact, GC.auto_compact=, GC.latest_compact_info and GC.verify_compaction_references. On 4.0.7 GC.compact returns the statistics of the compaction as a hash.

Source: Ruby 2.7 NEWS (GC.compact), Ruby 3.0 NEWS (GC.auto_compact) and Process.warmup

Two hundred thousand authors were created and nine in ten of them dropped, which leaves holes in the heap; after compaction the same live objects occupy a sixth of the pages (53 instead of 321 here), and the program’s own references (keepers) still work because moved objects are transparently updated. The page count after GC.compact is not guaranteed to shrink; it does so here because the program created a large block of garbage first.

What to know before using compaction:

Process.warmup (3.3) is the one-call version for the end of application boot. The documentation says that on CRuby it performs a major collection, compacts the heap, promotes all surviving objects to the old generation, precomputes the coderange of all strings, frees all empty heap pages and calls malloc_trim where available, and that the actual optimisations are implementation-specific and may change. In a pre-forking deployment call it once in the original process before the first fork, not in the workers.

GC.stat counts slots and pages, but the operating system sees the resident set size (RSS) of the process. The two diverge, which is the most common surprise when investigating memory.

Source: GC.stat

(The example reads the RSS from ps, which exists on macOS and Linux.) A million books raised the process from 19 MB to 133 MB. Clearing the array changed nothing until a collection ran; the collection freed about 31 MB and left more than a thousand empty pages that the heap keeps for reuse, so the process stays near 102 MB although almost nothing is alive. GC.compact did not release them here either. This is not a leak: the empty pages are reused by the next allocations, and the figure to watch for a leak is whether the live slot count keeps growing across repeated cycles of the same work. Process.warmup explicitly frees empty pages (see above), and for services the usual remedies are restarting workers after a number of requests, and, on Linux with glibc, limiting the number of malloc arenas (the MALLOC_ARENA_MAX environment variable) or using an alternative allocator such as jemalloc. Those two are general malloc behaviour rather than Ruby features, and were not run for this page.

The collector reads its parameters from environment variables at start-up. They were introduced with the generational collector (the Ruby 2.1 release notes list the first of them) and are not described on the 4.0 reference pages for GC, so treat them as implementation-specific and re-measure after every upgrade. The names below were read from the 4.0.7 binary, and the defaults come from Ruby itself: running ruby -w with a variable set prints a line with the default value, and a value outside the allowed range prints that it is ignored.

The effect is easy to see by running one program under different settings. The script builds 300,000 authors and prints what the collector did:

Source: GC.stat

Starting the first size pool with 600,000 slots cut the collections from 24 to 9, because the program no longer had to collect (and grow the heap step by step) while it was loading its data: the usual use of the initial-slot variables is a service whose steady-state heap size is known. Changing the growth factor or the malloc limit made no visible difference for this workload (the malloc limit shows up in GC.stat(:malloc_increase_bytes_limit), as the last run confirms), which is typical: most programs run best with the defaults. A sound procedure is to change one variable at a time, compare GC.stat(:count), GC.stat(:time) and the process RSS on a realistic workload, and keep the change only if the numbers justify it.

Ruby 3.4 split the built-in collector into its own source (gc/default/default.c) behind an interface defined in gc/gc_impl.h, so that other collectors can be plugged in. The release notes describe it as follows: configure Ruby with --with-modular-gc at build time, build a collector as a shared library (for example make modular-gc MODULAR_GC=default), and choose it at run time with the RUBY_GC_LIBRARY environment variable. An experimental collector based on MMTk, a memory-management toolkit, can be built with MODULAR_GC=mmtk and selected with RUBY_GC_LIBRARY=mmtk; it needs the Rust toolchain on the build machine. All of it is experimental, and it is a facility for implementers rather than something an application configures.

The 4.0.7 build used here was not configured with --with-modular-gc, so none of this was run: GC.config reports implementation: "default" and setting RUBY_GC_LIBRARY had no effect on this build (the process started and ran normally, without a message). Check GC.config[:implementation] to see which collector a process is using. The GC.config hash and the GC methods are the same interface whatever the implementation, but, as the documentation says, the entries that exist are implementation-specific.

ObjectSpace (the core part, plus the objspace library that extends it) is the tool for asking which objects exist. Its documentation says the library is mainly for memory-profiler developers and MRI developers, and that you should not use it unless you know the implementation. In practice a handful of calls cover most investigations:

The example hunts the classic leak: a cache that is filled and never trimmed. The AuthorIndex keeps a hash of authors by name for the life of the process:

Source: ObjectSpace.trace_object_allocations, ObjectSpace.each_object and ObjectSpace.reachable_objects_from

The reading of the result is the method. A thousand Author instances are still alive after the work is done, so something holds them; trace_object_allocations names the line that created one (line 11, the Shelf::Author.new call inside the cache); reachable_objects_from(index) shows that the index references only its class and one hash, and the hash is the container that grows (memsize_of of the index object alone is a meaningless 40 bytes, while its hash is 28 KB and growing). The fix is to bound the cache (an LRU), to key it weakly (next section), or to not cache at all. In a real process the trace is turned on briefly in a staging environment, and the sample object is chosen with a class filter, because tracing everything is expensive.

Two cautions from the documentation of each_object: it yields only live, non-immediate objects (small Integers, nil, true and static Symbols are not objects in the heap), and, because of a current Ractor limitation, once the process has entered multi-Ractor mode (the first Ractor.new) it no longer yields objects that are not Ractor-shareable. Counting instances after using Ractors can therefore under-report; see Ractors.

A cache that must not keep its entries alive needs weak references, which let the collector reclaim the referent. Object Lifecycle, Freezing and Copying explains the three families in detail; in the memory context the choices are:

Source: ObjectSpace::WeakKeyMap and WeakRef

Of the 100 title strings the cache saw, only the 10 still referenced from kept survived the collection, and their values (here the length) are still there. A WeakRef to an object nothing else references reports nil for weakref_alive? after the collection (the documentation says it returns true while the referent is alive; the library returns nil, which is falsy, once it has been collected). Weak structures are allowed to drop entries, not required to do so at a given moment: because the collector scans the machine stack conservatively, a stale pointer to an object can keep it alive a little longer, so tests that assert that something was collected should call GC.start and tolerate either outcome, or run the work in a method that has returned.

Memory problems come in two forms. A leak is growth of the live object count that never stops: something still references objects the program no longer needs, almost always a global, a class-level collection, a long-lived cache, a registry of callbacks or a thread-local that is never emptied. Bloat is a steady state that is simply too large, or too wasteful in allocations (with the collector time that goes with them). The tools above separate them: a trend in GC.stat(:heap_live_slots) or in ObjectSpace.count_objects across repeated identical work means a leak, which each_object, reachable_objects_from and allocation tracing then localise; a high but flat figure means bloat.

Tutorials and book chapters on performance that were written for Ruby 2.x or early 3.x often describe a simpler collector than the one in 4.0. The points worth correcting, each of which is shown above: