Overview

JavaScript engines like V8 constantly evolve to improve performance. One key area is how numbers are handled, especially when they exceed the integer range or require fractional values. Traditionally, heap-allocated numbers (HeapNumbers) are immutable—each update creates a new object. This can cause unnecessary allocation overhead in hot code paths, such as custom random number generators. This tutorial explores a real-world optimization V8 engineers applied to the async-fs benchmark in the JetStream2 suite, where making HeapNumbers mutable delivered a 2.5x speedup. We'll walk through the problem identification, technical details, implementation steps, and common pitfalls.

Prerequisites

Before diving in, you should be familiar with:

• Basic JavaScript syntax and how Math.random works.
• Concepts of a JavaScript engine (heap, stack, garbage collection).
• V8's internal object representation (SMIs, HeapNumbers, pointers).
• Proficiency with profiling tools (e.g., d8 with --trace-gc).

This guide is written for intermediate-to-advanced developers interested in engine internals and performance optimization.

Step-by-Step Optimization

1. Recognize the Performance Hotspot

The async-fs JavaScript file system benchmark relies on a deterministic pseudo-random number generator for reproducible behavior. The generator repeatedly updates a seed variable:

let seed;
Math.random = (function() {
  return function () {
    seed = ((seed + 0x7ed55d16) + (seed << 12))  & 0xffffffff;
    seed = ((seed ^ 0xc761c23c) ^ (seed >>> 19)) & 0xffffffff;
    seed = ((seed + 0x165667b1) + (seed << 5))   & 0xffffffff;
    seed = ((seed + 0xd3a2646c) ^ (seed << 9))   & 0xffffffff;
    seed = ((seed + 0xfd7046c5) + (seed << 3))   & 0xffffffff;
    seed = ((seed ^ 0xb55a4f09) ^ (seed >>> 16)) & 0xffffffff;
    return (seed & 0xfffffff) / 0x10000000;
  };
})();

The seed variable is stored in a ScriptContext—a special array holding variables accessible across the script. In V8's default 64-bit configuration, each ScriptContext slot is a tagged 32-bit value (either a Small Integer (SMI) or a compressed pointer to a heap object). If seed exceeds the 31-bit SMI range (due to bitwise operations), it becomes a HeapNumber—a 64-bit floating-point object stored on the garbage-collected heap. Every assignment to seed then allocates a new immutable HeapNumber. Profiling reveals this allocation as a major bottleneck.

2. Profile the Allocation Overhead

Use V8's built-in profiler (e.g., d8 --prof script.js) or trace garbage collection with --trace-gc. In the async-fs benchmark, GC logs show thousands of HeapNumber allocations per second, leading to frequent minor GC pauses. The allocation rate directly correlates with the number of Math.random calls. In contrast, if seed could be updated in-place, allocation overhead would vanish.

3. Understand the Limitation of Immutable HeapNumbers

Historically, HeapNumbers are immutable—their double value cannot change after creation. This design simplifies garbage collection and optimizes for common use where numbers are rarely mutated. However, when a variable is updated frequently (like seed), the engine must allocate a new HeapNumber each time, while the old one becomes garbage.

To verify, you can inspect memory addresses (in a debug build) and notice that each assignment to seed changes the pointer in the ScriptContext, not the value at the pointed address.

4. Implement Mutable Heap Numbers

The optimization involves making HeapNumbers mutable for specific slots. In V8, this was achieved by marking certain HeapNumbers as “mutable” via a new tag or a dedicated type. When the engine detects that a HeapNumber is repeatedly overwritten, it can reuse the same object and update its internal double value in place, instead of allocating fresh memory.

Key implementation steps (conceptually):

1. Identify hot variables: Profile to find variables that are stored as HeapNumbers and updated frequently. The seed variable is a clear candidate.
2. Add an internal flag: Extend the HeapNumber object structure with a mutable flag. This may require changes to the object’s header or type.
3. Modify the assignment code: When writing to a mutable HeapNumber, inline the new double value directly into the existing object’s payload, avoiding allocation.
4. Update GC barriers: Ensure the garbage collector treats mutable HeapNumbers appropriately (e.g., they are not moved or deoptimized).

In V8’s actual implementation, the change was more nuanced—they introduced a new internal “mutable heap number” concept used primarily for ScriptContext slots that are written often. But the core idea remains: reuse and update in place.

5. Verify Results

After implementing mutable HeapNumbers for the seed variable, re-run benchmarks. The allocation count for HeapNumbers drops dramatically, and the async-fs benchmark score improves by 2.5x. GC pauses become rarer, and overall JetStream2 score sees a noticeable lift. Profiling shows that the bottleneck shifts away from number allocation to other parts of the code.

Common Mistakes

• Assuming SMIs are always used: Even if numbers start as SMIs, bitwise operations in JavaScript may produce values outside the 31-bit range, forcing conversion to HeapNumbers. Always verify the actual representation with tracing flags.
• Overlooking GC impact: Mutable HeapNumbers can cause issues with incremental marking or concurrent GC if not properly managed. Ensure write barriers are correctly placed.
• Applying mutation to all HeapNumbers: Mutating HeapNumbers that are shared or read-only can break semantics. Only target variables that are local and frequently updated (e.g., closure variables, script context slots).
• Not measuring twice: Without profiling, you might assume a different bottleneck. Always back optimization decisions with data.
• Forgetting about deoptimization: If V8 deoptimizes a function, mutable HeapNumbers may fall back to immutable allocation. Ensure engine optimizations (like TurboFan) are aware of the new mutable type.

Summary

Making HeapNumbers mutable for frequently updated numeric variables in V8 eliminates unnecessary allocations and drastically improves performance—up to 2.5x in the async-fs benchmark. This optimization requires careful identification of hot slots (like the seed in a custom Math.random), engine-level changes to support in-place updates, and thorough testing to avoid GC issues. For engine developers, it’s a reminder that even “immutable” objects can be optimized when mutation patterns are clear. For JavaScript developers, understanding how numbers are stored helps in writing engine-friendly code—though such optimizations are mostly internal to V8. The principle of “avoid allocation in hot loops” remains universal.