Skip to content
Tutorials Center
My learning

Topics

Lesson 111 of 134 ยท Testing and Tooling

YJIT and Ruby Performance Internals

Look under Ruby's hood. See how YJIT compiles hot code, how the garbage collector and object slots work, how to measure allocations and memory, and which habits help or hurt the JIT.

The lesson Performance Tips taught you to measure first and to fix algorithms before anything else. This lesson is for the next question: why does Ruby behave the way it does when you measure? Knowing what happens inside the interpreter lets you predict which code will be fast, understand a memory graph, and set the flags that matter in production.

Three machines are at work. The virtual machine runs your bytecode (see How Ruby Runs). The JIT compiler, YJIT, turns hot bytecode into native machine code. The garbage collector allocates and frees objects. Our runner uses the plain interpreter, so the JIT parts are explained and shown read-only, while the allocation and GC parts run live and are deterministic enough to print.

What a JIT does

An interpreter reads one bytecode instruction at a time and decides what to do. That flexibility has a price: for every a + b it must check what kind of objects a and b are, find the right method and call it. A JIT (just-in-time compiler) watches the program run, notices the code that executes again and again, and compiles that part into machine instructions for your CPU. The compiled version skips most of the decoding and can be specialized to the types it has actually seen.

YJIT is the JIT that ships with CRuby. It is written in Rust and uses a technique called lazy basic block versioning. A basic block is a straight run of instructions with no branches. YJIT compiles one block at a time, only when it is about to run, and it records what it learned about the types of values flowing in. Each block is then compiled with those assumptions built in, protected by a cheap check called a guard.

flowchart TD
  A["Method called"] --> B{"Called often enough?<br/>(hot)"}
  B -- no --> C["Interpreter runs bytecode"]
  B -- yes --> D["YJIT compiles the next<br/>basic block to machine code"]
  D --> E["Run native code with<br/>type guards"]
  E --> F{"Guard still true?"}
  F -- yes --> E
  F -- no --> G["Side exit: compile a new version<br/>or fall back to the interpreter"]
  G --> C

Hot code is compiled block by block; when a guard fails, execution leaves the compiled code and may build a second version.

Because of the guards, JIT-friendly code is code whose types stay predictable. A method that always receives integers compiles to tight integer arithmetic. A method that receives integers, strings, nil and hashes in turn is said to be polymorphic (many shapes) and cannot be specialized as much. This is also why dynamic tricks that redefine methods or constants at run time can throw away compiled code: the assumptions no longer hold.

Turning YJIT on

You need no code changes. Choose one of these, depending on how the program is started:

Terminal
# read-only example: shell commands, not run here
ruby --yjit app.rb
RUBY_YJIT_ENABLE=1 bundle exec puma
RUBYOPT="--yjit" bundle exec sidekiq
ruby --yjit --yjit-exec-mem-size=96 app.rb     # raise the code memory limit (MiB)
ruby --yjit --yjit-stats app.rb                # print statistics at exit
Ruby
# read-only example: switch on at runtime, for instance after boot and warm-up
RubyVM::YJIT.enable if defined?(RubyVM::YJIT)
puts RubyVM::YJIT.enabled?

The trade-offs are simple. YJIT uses extra memory for the generated code (bounded by --yjit-exec-mem-size, which has a sensible default) and spends a short warm-up period compiling. After warm-up, typical Rails applications run noticeably faster. Short scripts that finish in a fraction of a second gain nothing, and may even lose a little, because they exit before the compiled code pays off.

A newer experimental compiler named ZJIT exists in Ruby 4.0. It compiles whole methods and is meant for future gains; today, YJIT is the one to use in production. Always benchmark your own application with and without the flag, and read the notes for your exact Ruby version.

Writing JIT-friendly Ruby

You rarely need to contort your code for a JIT, but these habits help it and cost nothing:

  • Keep types stable. A variable or argument that is always an Integer is better than one that is sometimes nil.
  • Initialize every instance variable in initialize, in the same order. Since Ruby 3.2 objects use shapes: all objects whose instance variables were added in the same order share a layout, so reads become a fast fixed-offset lookup. Adding variables in different orders or at random later moments makes more shapes and slower access.
  • Prefer plain method calls and blocks to send, method_missing and eval in hot loops (method_missing is wonderful for flexibility, but it is the slow path).
  • Do not redefine methods or reopen constants in the middle of a hot path. Do metaprogramming at start-up, then leave it alone.

Objects, slots and memory

Everything you create in Ruby is an object managed by the garbage collector. CRuby allocates objects in fixed-size slots that live on pages of the heap. Small values fit in a slot directly: an array of a few elements, a short string and a small object can be stored embedded inside the slot. Larger ones keep a pointer to a separate chunk of memory (malloc). Integers that fit in a machine word (Fixnum-sized values), nil, true, false and symbols are immediate values: they are encoded in the reference itself and are never allocated.

That explains a classic puzzle: why does 1.object_id stay the same for every 1 while two copies of the same string differ?

Ruby Immediate values versus allocated objects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Small integers, symbols and nil are the same object every time, so comparing them by identity is true. Two string literals are separate objects with equal contents. The unary minus on a string (-"text") deduplicates it: Ruby keeps one frozen copy in a table and returns it. A huge integer such as 2**70 is a heap object, so two computations give two objects.

Counting allocations

Allocation count is the most reliable metric for "how much work will the garbage collector have?", because unlike timing it does not change from run to run. GC.stat(:total_allocated_objects) is a counter that only grows. Take it before and after a block and subtract. The # frozen_string_literal: true comment at the top of a file makes every plain string literal in it frozen and shared, so a literal inside a loop stops allocating.

Ruby How many objects does each version allocate?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Every comparison prints true, and none depends on how fast your computer is. This is the style of measurement to prefer when you tune allocation-heavy code. Notice that the first result also demonstrates the effect of frozen string literals directly; without the magic comment the "shared" loop would allocate a string per iteration.

The garbage collector

Ruby's collector finds objects that can no longer be reached from your program and frees their slots. Some facts explain nearly every GC graph you will see:

  • It is generational. Most objects die young, so Ruby tracks "young" and "old" objects. A minor GC examines only young objects and is quick. A major GC examines everything and is rarer and slower. An object that survives a few minor collections is promoted to old.
  • It is incremental, so a major collection is split into slices that interleave with your program to keep pauses short.
  • Objects do not move by default, but GC.compact can compact the heap to fight fragmentation.
  • The cost of a collection depends on how many live objects there are, not on how much garbage there is. A program with a huge live data set pays more for every major GC.
stateDiagram-v2
  [*] --> Young: allocated
  Young --> Freed: unreachable at minor GC
  Young --> Old: survives a few minor GCs
  Old --> Freed: unreachable at major GC
  Freed --> [*]

Most objects die young and are freed cheaply; objects that live on become old and are examined only by major collections.

The conclusion is practical: fewer allocations mean fewer collections, and retaining objects you no longer need (in a global cache, a growing log array, a constant, a long-lived closure) is what makes memory climb. Let us watch both sides.

Ruby Garbage versus retained objects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Dropping the last reference (kept = nil) makes the strings unreachable, so the next collection frees them. If kept had been a constant or a class-level hash, they would stay forever, and that is the shape of most Ruby "memory leaks": the objects are not lost, they are still referenced. When you hunt one, count objects by class over time (ObjectSpace.count_objects, or ObjectSpace.each_object(Class) in a debugging session), or use the memory_profiler gem.

Tuning knobs worth knowing

GC settings are environment variables, and you should change them only after measuring.

Terminal
# read-only example: environment variables, not run here
RUBY_GC_HEAP_INIT_SLOTS=600000      # start with a larger heap to avoid early growth
RUBY_GC_HEAP_GROWTH_FACTOR=1.2      # how fast the heap expands
MALLOC_ARENA_MAX=2                  # glibc: fewer malloc arenas, less fragmentation
LD_PRELOAD=libjemalloc.so ruby app.rb   # a different allocator often lowers memory

For a threaded server, the glibc arena setting and jemalloc are well-known fixes for slowly growing resident memory that is not caused by Ruby objects at all. For long-lived web workers, forking after boot lets child processes share memory pages (copy-on-write), which is the reason servers such as Puma in cluster mode load the application before forking.

A measurement workflow

  1. Reproduce the problem with a script or a load test, so you can run it repeatedly.
  2. Decide the metric: wall time, allocations (GC.stat), live objects, or resident memory.
  3. Profile (see Benchmarking and Profiling) to find the hot method.
  4. Change one thing, such as removing an allocation in that method.
  5. Re-measure, then flip YJIT on and off to see how it interacts.

Remember that the JIT multiplies what your code already does. It makes a good algorithm quicker, but it cannot change an algorithm's complexity or remove time spent waiting on a database or network.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does YJIT compile, and when?

    YJIT uses lazy basic block versioning: it waits until code is hot, compiles blocks as they are reached, and specializes them to the types it has seen.
  2. 2. Which code is generally easiest for YJIT to speed up?

    Stable types let the compiled code rely on cheap guards. Constant type changes or redefinitions force side exits and recompilation.
  3. 3. Why does 1.equal?(1) return true while "a".equal?("a") returns false (without frozen literals)?

    Immediate values live inside the reference and are identical wherever they appear. Strings are heap objects, so two literals are two objects with equal contents.
  4. 4. What usually causes a Ruby 'memory leak'?

    The collector only frees unreachable objects. Anything that stays reachable is kept, even if your program no longer needs it.
  5. 5. Which is the most stable metric for comparing the GC pressure of two versions of a function?

    Allocation counts do not vary with machine load, so they make repeatable before and after comparisons.

Summary

  • YJIT compiles hot code block by block and relies on type guards; stable types and stable method definitions keep compiled code valid.
  • Enable it with --yjit, RUBY_YJIT_ENABLE=1 or RubyVM::YJIT.enable; expect extra memory and a warm-up, and benchmark your own app.
  • Immediate values (small integers, symbols, nil, booleans) never allocate; strings, arrays, hashes and big numbers do. Frozen and deduplicated strings can be shared.
  • Initialize instance variables consistently so objects share a shape.
  • The GC is generational and incremental; its cost follows the number of live objects, so retaining things you no longer need is what hurts.
  • Measure allocations with GC.stat(:total_allocated_objects) and live objects with ObjectSpace.count_objects; change GC and allocator settings only with evidence.

Next: Ruby on Rails Overview