V8 on Opensource internals

Scavenging the Young Generation: How V8 Copies Live Objects in Milliseconds

Jay Hubbert — Wed, 21 Oct 2026 18:50:00 +0000

TL;DR: V8’s young generation is two semi-spaces. A scavenge copies every live object from the from-space into the to-space with Cheney’s copying algorithm, then swaps them. The copy is what makes the collection cheap: no marking, no free lists - dead objects are simply not copied. The trick that makes it parallel-safe is a relaxed compare-and-swap on the object’s map word: whoever wins the CAS owns the copy, and the losers read the winner’s forwarding address out of the same word.

JavaScript allocates like a program that never frees anything, and the heap grows and shrinks as objects die. V8 does not want to run a general-purpose collector every few milliseconds - the pause would swamp the program.

So V8 splits the problem in two. Freshly allocated objects are cheap to reclaim: if almost nothing is going to survive, the fastest way to find the garbage is not to find it at all, but to copy the survivors out of the way and let the rest evaporate. That is the scavenger, and it is why a young collection in V8 is measured in single-digit milliseconds.

Two semi-spaces and a swap

 cpp
 
 
// src/heap/new-spaces.h:35
enum SemiSpaceId { kFromSpace = 0, kToSpace = 1 };

// -----------------------------------------------------------------------------
// SemiSpace in young generation
//
// A SemiSpace is a contiguous chunk of memory holding page-like memory chunks.
// The mark-compact collector uses the memory of the first page in the from
// space as a marking stack when tracing live objects.

The mutator allocates into the to-space. When the scavenge starts, the two are swapped, and the to-space becomes the from-space:

 cpp
 
 
// src/heap/new-spaces.cc:668
void SemiSpaceNewSpace::SwapSemiSpaces() {
 // Flip the semispaces. After flipping, to space is empty and from space has
 // live objects.
 SemiSpace::Swap(&from_space_, &to_space_);
 to_space_.Reset();
 from_space_.Reset();
 quarantined_size_ = 0;
 allocation_top_ = kNullAddress;
 DCHECK_EQ(0u, Size());

Swapping two pointers is the whole “flip”. There is no per-object work, no free list to walk, no mark bits to clear. After the swap the to-space is empty and ready for the mutator, and the from-space holds a contiguous block of objects of which, typically, most are garbage.

The scavenge is a one-liner in the heap:

 cpp
 
 
// src/heap/heap.cc:2617
void Heap::Scavenge() {
 DCHECK_NOT_NULL(new_space());
 DCHECK(!incremental_marking()->IsMarking());

 TRACE_GC(tracer(), GCTracer::Scope::SCAVENGER_SCAVENGE);
 SetGCState(SCAVENGE);

 // Implements Cheney's copying algorithm
 scavenger_collector_->CollectGarbage();

 SetGCState(NOT_IN_GC);
}

The paging allocator

The to-space is not one big contiguous allocation region. It is a list of pages, and the allocator is a bump pointer that spills onto a new page when it runs out - filling the remainder of the old page with a filler object so that the scavenger’s page walker can still find boundaries:

 cpp
 
 
// src/heap/new-spaces.cc:722
std::optional<std::pair<Address, Address>> SemiSpaceNewSpace::Allocate(
 int size_in_bytes, AllocationAlignment alignment) {
 size_in_bytes = ALIGN_TO_ALLOCATION_ALIGNMENT(size_in_bytes);
 Address top = allocation_top();
 if (top) {
 DCHECK_SEMISPACE_ALLOCATION_TOP(allocation_top(), to_space_);
 Address high = to_space_.page_high();
 int filler_size = MainAllocator::GetFillToAlign(top, alignment);
 int aligned_size_in_bytes = size_in_bytes + filler_size;

 if (top + aligned_size_in_bytes <= high) {
 IncrementAllocationTop(high);
 return std::pair(top, high);
 }

 int remaining_in_page = static_cast<int>(high - top);
 heap()->CreateFillerObjectAt(top, remaining_in_page);
 SetAllocationTop(high);

The mutator allocates from the top of the current page; when the page runs out, the tail is filled with a filler object and a fresh page is appended.

There is a second, subtler mechanism in the same function: allocation buffer parking. When the mutator’s linear allocation buffer does not fill a page, the leftover tail is parked so a later allocation can reuse it, as long as the tail is at least 4 KB (kAllocationBufferParkingThreshold, new-spaces.h). Parking is only allowed outside a GC - during a collection the space belongs to the scavenger.

During the GC the allocator plays a different game. Because several scavenger threads allocate into the same to-space concurrently, the linear allocation buffer handed to each thread has to be limited so that two threads never think they own the same bytes:

 cpp
 
 
// src/heap/main-allocator.cc:501
 if (allocator_->in_gc()) {
 // During GC we allow multiple LABs in new space and since Allocate() above
 // returns the whole remaining page by default, we limit the size of the LAB
 // here.
 size_t used = std::max(aligned_size_in_bytes, kLabSizeInGC);
 limit = std::min(end, start + used);

Cheney’s algorithm: the worklists

Cheney’s copying algorithm is the classic answer to “copy the live set without marking it”. The scavenger implements it with two worklists - one for objects copied into the to-space, one for objects promoted to old space

and the objects on those worklists are the grey set. The root scanner supplies the initial work:

 cpp
 
 
// src/heap/scavenger.cc:280
class Scavenger {
 public:
 static constexpr int kScavengedObjectListSegmentSize = 256;

 struct ScavengedObjectListEntry {
 Tagged<HeapObject> heap_object;
 Tagged<Map> map;
 SafeHeapObjectSize size;
 };

 using ScavengedObjectList =
 ::heap::base::Worklist<ScavengedObjectListEntry,
 kScavengedObjectListSegmentSize>;

The worklist is a segmented worklist of 256-entry chunks, and each scavenger thread has a local one plus a shared global one, so threads do not contend on a single queue.

The main loop drains both worklists, and the copies it makes feed back into the worklist - that is the whole algorithm:

 cpp
 
 
// src/heap/scavenger.cc:2538
void Scavenger::Process(JobDelegate* delegate) {
 ScavengerCopiedObjectVisitor copied_object_visitor(this);
 ScavengerPromotedObjectVisitor promoted_object_visitor(this);

 bool done;
 size_t objects = 0;
 do {
 done = true;
 ScavengedObjectListEntry entry;
 while (!ShouldEagerlyProcessPromotedList() &&
 local_copied_list_.Pop(&entry)) {
 copied_object_visitor.Visit(entry.map, entry.heap_object, entry.size);
 done = false;
 if (delegate && ((++objects % kInterruptThreshold) == 0)) {
 if (!local_copied_list_.IsGlobalEmpty()) {
 delegate->NotifyConcurrencyIncrease();
 }
 }
 }

The visitor that pops an entry from the copied list walks the object’s fields, and each field that points into the from-space triggers another copy - which pushes onto the copied list. The loop ends when both lists are empty. No marking bit is ever set on a young object.

The ShouldEagerlyProcessPromotedList check is a scheduling heuristic: if the promoted list is getting long, it is drained first, because promoted objects live in old space and their fields may point at old-to-old references that other threads need.

The forwarding CAS

When the scavenger copies an object, it cannot just copy it - another thread might be copying the same object at the same time, because two different fields can point at it. V8 solves this by using the object’s map word - the word that normally holds the pointer to its map - as a forwarding address. The first thread to win a compare-and-swap owns the copy; the others read the winner’s address out of the same word:

 cpp
 
 
// src/heap/scavenger.cc:1972
 // This CAS can be relaxed because we do not access the object body if the
 // object was already copied by another thread. We only access the page header
 // of such objects and this is safe because of the memory fence after page
 // header initialization.
 if (!source->relaxed_compare_and_swap_map_word_forwarded(
 MapWord::FromMap(map), target)) {
 // Other task migrated the object.
 allocator_.FreeLast(space, target, object_size);
 const MapWord map_word = source->map_word(kRelaxedLoad);
 UpdateHeapObjectReferenceSlot(slot, map_word.ToForwardingAddress(source));
 SynchronizePageAccess(*slot);
 DCHECK(!Heap::InFromPage(*slot));
 return true;
 }

 // Copy the content of source to target. Note that we do this on purpose
 // *after* the CAS. This avoids copying of the object in the (unlikely)
 // failure case. It also helps us to ensure that we do not rely on non-relaxed
 // memory ordering for the CAS above.
 target->set_map_word(map, kRelaxedStore);
 Heap::CopyBlock(target.address() + kTaggedSize,
 source.address() + kTaggedSize,
 SafeHeapObjectSize(object_size.value() - kTaggedSize));

Three things to notice. The CAS is relaxed, because a thread that loses the race never touches the object body - it only reads the page header, which is protected by the memory fence after page header initialisation. The copy happens after the CAS, so a losing thread never does a wasted memcpy. And the losing thread still has to fix up its slot: it reads the forwarding address the winner wrote and points its slot there. That last point is the crux - after the CAS, every thread that finds the object can find its new address.

Promotion: the age mark

Not everything is copied into the to-space. Objects that are old enough get promoted to old space instead, so the young generation does not keep re-copying the same long-lived objects forever.

The age is tracked by an age mark: a single address separating the part of the space holding objects that already survived a collection from the part holding fresh allocations.

 cpp
 
 
// src/heap/new-spaces-inl.h:92
bool SemiSpaceNewSpace::ShouldBePromoted(Address object) const {
 return IsAddressBelowAgeMark(object);
}

The check is per-page, using a page flag, so that it does not need a metadata table lookup:

 cpp
 
 
// src/heap/new-spaces-inl.h:80
 if (!chunk->InNewSpaceBelowAgeMark()) {
 return false;
 }

 const Address age_mark = age_mark_;
 const bool on_age_mark_page =
 chunk->address() < age_mark &&
 age_mark <= chunk->address() + NormalPage::kPageSize;
 DCHECK_EQ(chunk->Metadata()->ContainsLimit(age_mark), on_age_mark_page);
 return !on_age_mark_page || address < age_mark;

The age mark is set at the end of every collection, to the top of the survivor region:

 cpp
 
 
// src/heap/new-spaces.cc:429
void SemiSpaceNewSpace::SetAgeMarkAndBelowAgeMarkPageFlags() {
 age_mark_ = allocation_top();

 NormalPage* current_page = to_space().first_page();

 for (size_t i = 0; i < to_space_.quarantined_pages_count_; i++) {
 DCHECK_NOT_NULL(current_page);
 current_page->SetFlagNonExecutable(MemoryChunk::NEW_SPACE_BELOW_AGE_MARK);
 current_page = current_page->next_page();
 }

So the sequence is: the survivors of collection N are copied into the bottom of the to-space; the age mark is placed at the top of that survivor region; fresh allocations then fill the space above it. At collection N+1 the from-space contains survivors (below the mark) and fresh objects (above it), and the ones below the mark are promoted.

In other words: survive one scavenge, and you are promoted.

The three-way fallback

The decision to copy or promote is not a simple either/or. EvacuateObjectDefault has three attempts, in order:

 cpp
 
 
// src/heap/scavenger.cc:2126
 if (!ShouldBePromoted(object.address())) {
 // A semi-space copy may fail due to fragmentation. In that case, we
 // try to promote the object.
 if (SemiSpaceCopyObject(map, slot, object, object_size, object_fields))
 [[likely]] {
 return RememberedSetEntryNeeded(heap_, slot);
 }
 }

 // We may want to promote this object if the object was already semi-space
 // copied in a previous young generation GC or if the semi-space copy above
 // failed.
 if (PromoteObject<THeapObjectSlot, promotion_heap_choice>(
 map, slot, object, object_size, object_fields)) [[likely]] {
 return RememberedSetEntryNeeded(heap_, slot);
 }

Copy first, promote second, copy again third, and only then give up. The reason is fragmentation: the to-space may not have a contiguous run of the right size, in which case promotion into old space (which has free lists and different size classes) succeeds where the copy failed.

The three attempts also differ in what they record. A copied object is pushed onto the copied worklist; a promoted object onto the promoted worklist; and both update the pretenuring feedback:

 cpp
 
 
// src/heap/scavenger.cc:2008
bool Scavenger::SemiSpaceCopyObject(Tagged<Map> map, THeapObjectSlot slot,
 Tagged<HeapObject> object,
 SafeHeapObjectSize object_size,
 ObjectFields object_fields) {
 static_assert(std::is_same_v<THeapObjectSlot, FullHeapObjectSlot> ||
 std::is_same_v<THeapObjectSlot, HeapObjectSlot>,
 "Only FullHeapObjectSlot and HeapObjectSlot are expected here");
 DCHECK(heap()->AllowedToBeMigrated(map, object, NEW_SPACE));
 return TryMigrateObject(
 map, slot, object, object_size, NEW_SPACE,
 [this, map, object_fields, object,
 object_size](Tagged<HeapObject> target) {
 PretenuringHandler::UpdateAllocationSite(
 heap_, map, object, object_size, &local_pretenuring_feedback_);
 copied_size_ += object_size.value();
 if (object_fields == ObjectFields::kMaybePointers) {
 local_copied_list_.Push({target, map, object_size});
 }
 });
}

Note the ObjectFields::kMaybePointers check: an object with no pointers in it - a number, a boolean - does not need to be on a worklist, because there is nothing to trace from it.

Pretenuring: allocation-site feedback

The PretenuringHandler::UpdateAllocationSite call above is more than bookkeeping. When V8 sees that objects allocated at a particular allocation site keep surviving, it can allocate them directly in old space next time, so they never have to be scavenged at all. The scavenger is where that evidence is gathered: it knows which objects survived and how big they were, and merges the feedback into the heap’s pretenuring handler at the end of the collection. The young collector is also the profiler for the old one.

Special cases: large objects and strings

Large objects. Objects too big for a page live in a separate “new large object space”, which is also flipped at the start of the scavenge. They are never copied - they are promoted immediately, by writing a self-forwarding map word:

 cpp
 
 
// src/heap/scavenger.cc:2052
bool Scavenger::HandleLargeObject(Tagged<Map> map, Tagged<HeapObject> object,
 SafeHeapObjectSize object_size,
 ObjectFields object_fields) {
 // Quick check first: A large object is the first (and only) object on a data
 // page (code pages have a different offset but are never young). This check
 // avoids the page flag access.
 if (MemoryChunk::AddressToOffset(object.address()) !=
 MemoryChunkLayout::ObjectStartOffsetInDataPage()) [[likely]] {

Strings. Three string cases are special, and all are about avoiding a copy:

A thin string points at an internalized string that is always in old space, so the scavenger points the slot at the target and drops the thin string.
A cons string whose second half is empty is a “shortcut candidate” - already flattened. The scavenger points the slot at the first half and drops the cons string:

 cpp
 
 
// src/heap/scavenger.cc:2186
 if (shortcut_strings_ &&
 object->unchecked_second() == ReadOnlyRoots(heap()).empty_string()) {
 Tagged<HeapObject> first = Cast<HeapObject>(object->unchecked_first());

 UpdateHeapObjectReferenceSlot(slot, first);

A string that can be internalized in place is treated specially so that internalization does not have to copy the characters.

The “shortcut” trick is a nice illustration of the copying collector’s second-order effects: by not copying a flattened cons string and instead splicing it out, the scavenger collapses a two-object rope into one.

The parallel scavenge

The scavenge is not single-threaded, even though it is a stop-the-world pause. The main thread scans the roots while worker threads process the old-to-new remembered set - the pages of old space that may point into the young generation. The job is posted before the root scan starts, and the main thread participates while it scans:

 cpp
 
 
// src/heap/scavenger.cc:1737
 std::unique_ptr<JobHandle> job_handle = V8::GetCurrentPlatform()->PostJob(
 v8::TaskPriority::kUserBlocking, std::move(job));

 // Iterate roots on the main thread while background threads scavenge pages.
 {
 // Copy roots.
 TRACE_GC(heap_->tracer(), GCTracer::Scope::SCAVENGER_SCAVENGE_ROOTS);

The number of scavenger tasks is derived from the size of the young generation and the number of cores, capped at eight:

 cpp
 
 
// src/heap/scavenger.cc:1579
int NumberOfScavengeTasks(Heap* heap) {
 // The maximum number of scavenger tasks including the main thread. The actual
 // number of tasks is determined at runtime.
 static constexpr int kMaxScavengerTasks = 8;

 if (!v8_flags.parallel_scavenge) {
 return 1;
 }
 const int num_scavenge_tasks =
 static_cast<int>(
 SemiSpaceNewSpace::From(heap->new_space())->TotalCapacity()) /
 MB +
 1;

Each task gets its own Scavenger object with its own local worklists, and they publish into shared global worklists at the end. The ScavengerJobTask also computes the desired concurrency dynamically - if the work turns out bigger than the number of pages suggests, it asks the job system for more workers.

One detail worth noting: the scavenger explicitly asserts that incremental marking is not running:

 cpp
 
 
// src/heap/heap.cc:2619
 DCHECK(!incremental_marking()->IsMarking());

So the classic scavenger and the concurrent marker do not run at the same time. They interleave across collections instead: after a young collection, if the old generation has consumed enough of its allocation limit, V8 starts an incremental marking cycle, which then runs with the mutator until the next collection.

Growing and shrinking the young generation

The young generation is not a fixed size. V8 grows it when a lot survives and shrinks it when the mutator is idle.

 cpp
 
 
// src/heap/heap.cc:3684
 const bool should_grow =
 (new_space_->TotalCapacity() < new_space_->MaximumCapacity()) &&
 (survived_since_last_expansion_ > new_space_->TotalCapacity());

 if (should_grow) survived_since_last_expansion_ = 0;

 if (should_grow == should_shrink) return ResizeNewSpaceMode::kNone;
 return should_grow ? ResizeNewSpaceMode::kGrow : ResizeNewSpaceMode::kShrink;
}

The growth rule is the interesting one: grow only if the surviving bytes since the last expansion exceed the whole current capacity. V8 doubles the young generation only when the survivors are comparable in size to the entire space - a sign that the workload is allocating long-lived objects and would benefit from a bigger nursery. Growth is by a factor of two (semi_space_growth_factor, default 2).

The shrink rule fires when the allocation throughput drops below 1000 bytes per millisecond - the mutator is idle - and keeps at least twice the currently-used size, floored at the minimum capacity. The GC scheduler decides when any of this runs.

The bounds come from the physical memory size:

 cpp
 
 
// src/heap/heap.cc:4824
// static
size_t Heap::DefaultMinSemiSpaceSize() {
 return RoundUp(512 * KB, NormalPage::kPageSize);
}

// static
size_t Heap::DefaultMaxSemiSpaceSize(uint64_t physical_memory) {
 if (v8_flags.minor_ms) {
 static constexpr size_t kMinorMsMaxCapacity = 72 * MB;
 return RoundUp(kMinorMsMaxCapacity, NormalPage::kPageSize);
 }

So a semi-space starts at 512 KB and can grow to 32 MB (72 MB with the minor mark-sweep collector, 8 MB on low-end Android).

Trade-offs

What it buys. A young collection is a copy of the live set and nothing else. No marking, no sweeping, no free-list maintenance. The cost is proportional to what survives, not to what was allocated, and the swap that starts the collection is two pointer writes.

What it costs.

Copying is not free. Every survivor is memcpy’d. A workload where most objects survive has paid twice: once to copy, once to collect.
Fragmentation. The to-space is a bump allocator, so a large object can fail to fit and force a promotion. The three-way fallback in EvacuateObjectDefault exists because of this.
Promotion is not always right. An object promoted too early occupies old space, where the mark-compact collector will trace it forever.
The pause is still a pause. The scavenger is a stop-the-world event, even though its work is parallelised.

The bottom line

The scavenger is a copying collector with a two-pointer flip. Live young objects are copied from the from-space into the to-space with Cheney’s algorithm; dead ones are not copied, and the whole from-space becomes free memory in one pointer swap.

The two ideas that make it work in practice are the forwarding CAS on the map word - which lets several threads copy concurrently without locks and without double-copying - and the age mark, which decides when an object has earned a place in old space.

The mental model: the young generation is a nursery, and the scavenger moves the survivors into bigger pots.

The thing people get wrong

“The scavenger is a stop-the-world pause, so it is expensive.” It is a stop-the-world pause, but the work inside it is proportional to the live set and is spread across up to eight threads while the main thread scans roots. A young collection in V8 is typically single-digit milliseconds.

The opposite misconception is also common: “the scavenger frees the young generation, so memory usage drops.” It does not necessarily. The from-space is reused, not returned to the OS - the same pages come back as the to-space. Memory only drops when V8 shrinks the young generation or when the old generation is collected.

And the third: “objects are promoted when they get old.” They are promoted when they survive. The age mark is not a clock; it is a line drawn across the to-space at the end of each collection, and everything below it

everything copied out of the previous from-space - is promoted at the next one.

The Write Barrier: How V8 Knows Where a Moved Object Used to Live

Jay Hubbert — Wed, 21 Oct 2026 18:20:00 +0000

TL;DR: V8’s write barrier is not one thing. It is a four-tier machine

inline fast path, deferred out-of-line path, shared slow path, C++ slow path - that does up to three jobs at once: remembering old-to-new references for the generational collector, marking the value and preventing black-to-white references during incremental marking, and recording the slot of an old-to-old reference so that a compacting GC can find it again and rewrite it. The compacting part does not remember the old address of the moved object; it remembers where the pointer lives.

Every time V8’s mutator writes a heap pointer into a heap object, the garbage collector has to hear about it. Not always - but often enough that the “often enough” case has to be nearly free.

V8’s answer is a layered barrier that most stores never pay for. The interesting design is not the layering; it is the third job, the one that exists only because V8 has a moving collector.

Three jobs, one barrier

V8 ships a readme for the barrier, and it is worth reading before the code:

 cpp
 
 
// src/heap/WRITE_BARRIER.md:3
V8 uses a write barrier to inform the GC about changes to the heap by the mutator.
A write barrier is emitted for heap stores like `host.field = value`.
The write barrier is required for multiple purposes:
* Records old-to-new references for the generational GC to work.
* During marking it prevents black-to-white references during incremental/concurrent marking.
* During marking it records old-to-old references (pointers to objects on evacuation candidates)

Three jobs:

Generational. If an old object points at a young object, the young object has to survive the next scavenge, so the barrier records the slot.
Marking. During incremental or concurrent marking, the tri-colour invariant says a black object must not point at a white one. The barrier marks the value and, when necessary, shades the host.
Evacuation slot recording. If the value lives on a page the compacting collector wants to move, the collector needs to find every reference to it. The barrier records the slot.

The first two are well known. The third is where the “how does V8 know where a moved object used to live” question is answered.

The four-tier structure

The barrier is split into four tiers - inline fast path, deferred out-of-line path, shared slow path, C++ slow path - and the split is the same in the C++ path, in CSA, and in TurboFan. Tiers 1 and 2 are emitted per call site: the fast path is inline in the store, the deferred path is a branch target nearby. Tier 3 is a shared routine written in CSA. Tier 4 is C++ that may malloc.

The C++ entry point shows the shape of the whole thing:

 cpp
 
 
// src/heap/heap-write-barrier-inl.h:51
// static
void WriteBarrier::CombinedWriteBarrierInternal(Tagged<HeapObject> host,
 HeapObjectSlot slot,
 Tagged<HeapObject> value,
 WriteBarrierMode mode) {
 DCHECK_EQ(mode, UPDATE_WRITE_BARRIER);

 if constexpr (v8_flags.sticky_mark_bits.value()) {
 CombinedWriteBarrierInternalForStickyMarkbits(host, slot, value, mode);
 return;
 }

 MemoryChunk* host_chunk = MemoryChunk::FromHeapObject(host);
 // Fast path: Marking is off and the host objects is either in the young
 // generation or shared space, for which we don't require remembered sets.
 if (!host_chunk->PointersFromHereAreInteresting()) [[likely]] {
 return;
 }

 // Either marking is on, or the host objects is in the old (non-shared)
 // generation for which we record remembered sets.

 MemoryChunk* value_chunk = MemoryChunk::FromHeapObject(value);
 // Old to old writes can bail out when marking is off.
 if (!value_chunk->PointersToHereAreInteresting()) {
 return;
 }

 CombinedWriteBarrierInternalSlow(host, host_chunk, slot, value, value_chunk);
}

Two loads of a page-header flag and two predictable branches. That is the cost of the barrier for a store that does not need one.

The fast path: two page flags

The flags are per-page, not per-object, and they answer two questions:

kPointersFromHereAreInterestingMask - does this page contain objects whose outgoing pointers the GC cares about? False for young-generation pages and read-only pages.
kPointersToHereAreInterestingMask - does this page contain objects the GC might need to find references to? False for read-only pages and, during marking, for pages that are already black.

 cpp
 
 
// src/heap/memory-chunk.h:113
 static constexpr MainThreadFlags kAllFlagsMask = ~MainThreadFlags(NO_FLAGS);
 static constexpr MainThreadFlags kPointersToHereAreInterestingMask =
 POINTERS_TO_HERE_ARE_INTERESTING;
 static constexpr MainThreadFlags kPointersFromHereAreInterestingMask =
 POINTERS_FROM_HERE_ARE_INTERESTING;

The page granularity is what makes this cheap: a whole 256 KB page of young objects answers “not interesting” with a single flag test, so a store into a young object needs no barrier at all.

There is a subtlety in the fast path above that is easy to miss. The second check - “old to old writes can bail out when marking is off” - holds only because when marking is off there is nothing to mark and nothing to rewrite. During marking, an old-to-old write must be examined, because the value might now be on an evacuation candidate page.

The generational barrier: old to new

When the host is old and the value is young, the slot has to be recorded so the scavenger can find the young object through the old one. This is the OLD_TO_NEW remembered set, and it is what the scavenger reads.

 cpp
 
 
// src/heap/heap-write-barrier.cc:408
void WriteBarrier::GenerationalBarrierSlow(Tagged<HeapObject> host,
 Address slot,
 Tagged<HeapObject> value) {
 const LocalHeap* local_heap = LocalHeap::Current();
 MemoryChunk* host_chunk = MemoryChunk::FromHeapObject(host);
 MutablePage* host_page =
 SbxCast<MutablePage>(host_chunk->Metadata(local_heap->heap()->isolate()));
 if (local_heap->is_main_thread()) {
 RememberedSet<OLD_TO_NEW>::Insert<AccessMode::NON_ATOMIC>(
 host_page, host_chunk->Offset(slot));
 } else {
 RememberedSet<OLD_TO_NEW_BACKGROUND>::Insert<AccessMode::ATOMIC>(
 host_page, host_chunk->Offset(slot));
 }
}

Note that there are two remembered sets, not one: the main thread uses a non-atomic insert into OLD_TO_NEW, background threads an atomic insert into OLD_TO_NEW_BACKGROUND. The scavenger scans both.

The marking barrier: keeping the tri-colour invariant

During incremental or concurrent marking, the barrier must mark the value grey so it gets traced, and shade the host if the host is black and the value is white.

 cpp
 
 
// src/heap/marking-barrier-inl.h:20
template <typename TSlot, RecordYoungSlot kRecordYoung>
void MarkingBarrier::Write(Tagged<HeapObject> host, TSlot slot,
 Tagged<HeapObject> value) {
 DCHECK(IsCurrentMarkingBarrier(host));
 DCHECK(is_activated_ || shared_heap_worklists_.has_value());
 DCHECK(MemoryChunk::FromHeapObject(host)->IsMarking());

 MarkValue(host, value);

 // When recording slots to young pointers, we need to call RecordSlot even if
 // IsCompacting() returns true. This is because IsCompacting() simply returns
 // false when there are no evacuation candidates. New space pages are not
 // considered evacuation candidates and may still be relocated.
 if (slot.address() &&
 (static_cast<bool>(kRecordYoung) || IsCompacting(host))) {
 MarkCompactCollector::RecordSlot<TSlot, kRecordYoung>(host, slot, value);
 }
}

MarkValue handles the tri-colour logic (mark the value, and if the host is black and the value is white, shade the host). The RecordSlot call is the third job, and it is conditional on IsCompacting(host) - the host’s page must be one the compacting collector intends to move.

The evacuation barrier: how V8 knows where a moved object used to live

Here is the mechanism, and it is not what most people assume.

The barrier does not store the old address of the moved object. It stores the offset of the slot - the position of the pointer field inside the host page - in the OLD_TO_OLD remembered set.

 cpp
 
 
// src/heap/mark-compact-inl.h:73
 const MemoryChunk* value_chunk = MemoryChunk::FromHeapObject(value);
 if (!value_chunk->IsEvacuationCandidate() &&
 (!static_cast<bool>(kRecordYoung) ||
 !HeapLayout::InYoungGeneration(value_chunk, value))) {
 return;
 }

Note the early-out: the slot is only recorded if the value is on an evacuation candidate page. If the value is in a page that will not move, there is nothing to rewrite later, so nothing is recorded. The insert itself picks the remembered set that matches the kind of space the value is in:

 cpp
 
 
// src/heap/mark-compact-inl.h:97
 } else if (V8_LIKELY(!value_page->is_writable_shared()) ||
 host_page->heap()->isolate()->is_shared_space_isolate()) {
 DCHECK_EQ(host_page->heap(), value_page->heap());
 RememberedSet<OLD_TO_OLD>::Insert<AccessMode::ATOMIC>(
 host_page, host_chunk->Offset(slot.address()));

Now the compaction side. At the end of the mark-compact cycle, the collector walks the OLD_TO_OLD set and rewrites each recorded slot, and UpdateSlot does the actual rewrite by reading the old address out of the slot and following the forwarding pointer stored in the old object’s map word:

 cpp
 
 
// src/heap/mark-compact.cc:4423
 if (HeapLayout::InReadOnlySpace(heap_obj)) return;
 MapWord map_word = heap_obj->map_word(kRelaxedLoad);
 if (!map_word.IsForwardingAddress()) return;
 DCHECK_IMPLIES((!v8_flags.minor_ms && !Heap::InFromPage(heap_obj)),
 MarkCompactCollector::IsOnEvacuationCandidate(heap_obj) ||
 MemoryChunk::FromHeapObject(heap_obj)
 ->Metadata()
 ->evacuation_was_aborted());
 typename TSlot::TObject target = MakeSlotValue<TSlot, reference_type>(
 map_word.ToForwardingAddress(heap_obj));
 // Needs to be atomic for map space compaction: This slot could be a map
 // word which we update while loading the map word for updating the slot
 // on another page.
 slot.Relaxed_Store(target);

So the flow is: the barrier remembers where the pointer is; the collector later reads what the pointer was from that slot; the moved object carries its new address in its own map word as a forwarding pointer; and the slot is overwritten with the new address.

The object itself does the remembering. The moving collector already has to write a forwarding address into every object it moves, so the “where did this object used to live” question is answered by the object, not by the barrier.

The remembered set is a bitmap, not a list

One more thing makes this affordable. The remembered set is not a list of slot addresses. It is a bitmap, one bit per pointer-sized slot in the page:

 cpp
 
 
// src/heap/base/basic-slot-set.h:277
 static constexpr int kCellsPerBucket = 32;
 static constexpr int kCellsPerBucketLog2 = 5;
 static constexpr int kCellSizeBytesLog2 = 2;
 static constexpr int kCellSizeBytes = 1 << kCellSizeBytesLog2;
 static constexpr int kBitsPerCell = 32;
 static constexpr int kBitsPerCellLog2 = 5;
 static constexpr int kBitsPerBucket = kCellsPerBucket * kBitsPerCell;
 static constexpr int kBitsPerBucketLog2 =
 kCellsPerBucketLog2 + kBitsPerCellLog2;

A bucket is 32 cells of 32 bits, i.e. 1024 bits, covering 1024 slots. With V8’s default 256 KB page and 8-byte tagged slots, a page has 32768 slots, so a fully-populated slot set is 32768 bits - 4 KB - for a 256 KB page. One bit per slot.

This is also why the CSA implementation can do the insert without any allocation in the common case: the slot set is allocated lazily per page, and the insert is a bit-set.

When the barrier is skipped

The barrier is elided in several cases: storing a Smi, storing a read-only object, and storing into the most recent young allocation - an “initializing store”, where the host was allocated in the young generation and no GC point has occurred since.

The third rule is the clever one, and it is safe for a non-obvious reason:

 cpp
 
 
// src/heap/WRITE_BARRIER.md:26
None of the three write barrier kinds are necessary for such stores:
* **Old-to-new (generational) barrier:** Not needed because the host object is itself young, so there is no old-to-new reference to record.
* **Old-to-old (evacuation) barrier:** Not needed because the host object is young, so there is no old-to-old slot to track. The GC can still relocate young objects during a GC; new-to-new slots are discovered by scanning the young generation during the atomic GC pause. This is cheap because the young generation is usually small relative to the full heap size. Note that old-to-new references are still recorded by the generational barrier even during incremental marking. That way we discover all references to young objects.
* **Marking barrier:** This is the trickiest case. Concurrent marking bails out of tracing objects that reside in the current new space LAB (linear allocation buffer) and pushes them into an "on hold" queue. This prevents such objects from becoming black — they remain grey. Grey objects are marked but are also contained in the worklist - so they will be traced at some point in the future. All of this means that the host object for such cases can never be black - so we also do not need a WB to prevent black-to-white references here. This is also where the *most recently allocated object* limitation comes from.

Read that third bullet carefully. The reason a freshly allocated object needs no marking barrier is not that it is young. It is that concurrent marking refuses to blacken objects in the current linear allocation buffer - they go on an “on hold” queue and stay grey. A grey host can never violate the tri-colour invariant, because grey means “will be traced again”.

The C++ side has the same rules, and the debug build checks them:

 cpp
 
 
// src/heap/heap-write-barrier-inl.h:525
// static
template <typename HostType, typename ValueType>
bool WriteBarrier::IsRequiredCommon(HostType host, ValueType value) {
 if (IsSmi(value)) {
 return false;
 }
 if (value.IsCleared()) {
 return false;
 }
 Tagged<HeapObject> target = value.GetHeapObject();
 if (ReadOnlyHeap::Contains(target)) {
 return false;
 }
 if constexpr (std::is_same_v<HostType, const HeapObject*>) {
 return !IsMostRecentYoungAllocation(host->address());
 } else {
 return !IsMostRecentYoungAllocation(host.address());
 }
}

SKIP_WRITE_BARRIER is a mode that a caller asserts; in a verification build, VerifySkipWriteBarrier checks the assertion and fails the process if it is wrong.

How the barrier is generated: CSA and TurboFan

The shared slow path is written in CSA, in WriteBarrierCodeStubAssembler. The generational insert is the interesting part, because it is the one that has to touch a per-page bitmap:

 cpp
 
 
// src/builtins/builtins-internal-gen.cc:175
 TNode<IntPtrT> slot_offset = IntPtrSub(slot, chunk);
 TNode<IntPtrT> num_buckets_address =
 IntPtrSub(slot_set, IntPtrConstant(SlotSet::kNumBucketsSize));
 TNode<IntPtrT> num_buckets = UncheckedCast<IntPtrT>(
 Load(MachineType::Pointer(), num_buckets_address, IntPtrConstant(0)));

 // Load bucket
 TNode<IntPtrT> bucket =
 LoadBucket(slot_set, slot_offset, num_buckets, &slow_path);

 // Update cell
 SetBitInCell(bucket, slot_offset);
 Goto(&next);

 BIND(&slow_path);
 {
 TNode<ExternalReference> function =
 ExternalConstant(ExternalReference::insert_remembered_set_function());
 CallCFunctionWithCallerSavedRegisters(
 function, MachineTypeOf<Int32T>::value, fp_mode,
 std::make_pair(MachineTypeOf<IntPtrT>::value, page),
 std::make_pair(MachineTypeOf<IntPtrT>::value, slot_offset));
 Goto(&next);
 }

The slow path is the C++ Heap::InsertIntoRememberedSetFromCode, the only tier that may have to allocate the slot set for a page.

The marking side of the CSA barrier encodes the evacuation-candidate test as a single fused condition:

 cpp
 
 
// src/builtins/builtins-internal-gen.cc:467
 void IsValueUnmarkedOrRecordSlot(TNode<IntPtrT> value, Label* true_label,
 Label* false_label) {
 // This code implements the following condition:
 // IsUnmarked(value) ||
 // OnEvacuationCandidate(value) &&
 // !SkipEvacuationCandidateRecording(value)

 // 1) IsUnmarked(value) || ....
 GotoIf(IsUnmarked(value), true_label);

 // 2) OnEvacuationCandidate(value) &&
 // !SkipEvacuationCandidateRecording(value)
 GotoIfNot(IsPageFlagSet(value, MemoryChunk::kEvacuationCandidateMask),
 false_label);

If the value is unmarked, the barrier must run (to mark it). If it is marked but on an evacuation candidate page, the barrier must run (to record the slot). Otherwise it can be skipped entirely.

TurboFan emits the barrier as a dedicated machine opcode, kArchAtomicStoreWithWriteBarrier, whose inline fast path is:

 cpp
 
 
// src/compiler/backend/x64/code-generator-x64.cc:2136
 if (mode > RecordWriteMode::kValueIsPointer) {
 __ JumpIfSmi(value, ool->exit());
 }
#if V8_ENABLE_STICKY_MARK_BITS_BOOL
 __ CheckPageFlag(object, scratch0, MemoryChunk::kIncrementalMarking,
 not_zero, ool->stub_call());
 __ CheckMarkBit(object, scratch0, scratch1, carry, ool->entry());
#else // !V8_ENABLE_STICKY_MARK_BITS_BOOL
 static_assert(WriteBarrier::kUninterestingPagesCanBeSkipped);
 __ CheckPageFlag(object, scratch0,
 MemoryChunk::kPointersFromHereAreInterestingMask,
 not_zero, ool->entry());
#endif // !V8_ENABLE_STICKY_MARK_BITS_BOOL
 __ bind(ool->exit());

Three things happen here, in order: the store itself is emitted (the EmitTSANAwareStore call above it), a Smi value short-circuits to the exit label, and then the page flag decides whether to fall into the out-of-line OutOfLineRecordWrite block. That block checks the value page flag - the POINTERS_TO_HERE_ARE_INTERESTING test - and, if the value is uninteresting, jumps back out without doing any work.

That is the whole barrier for a typical store: a Smi test, a page flag test, and a not-taken branch.

The sandbox: external and trusted pointers

With the sandbox enabled, some heap fields do not hold a heap pointer at all. They hold an index into a side table of external pointers, or a tagged indirect pointer into the trusted space. Those need their own barriers, because the GC has to mark the table entry and not the slot.

 cpp
 
 
// src/heap/heap-write-barrier.cc:143
void WriteBarrier::MarkingSlow(Tagged<HeapObject> host,
 ExternalPointerSlot slot,
 ExternalPointerHandle handle) {
#ifdef V8_COMPRESS_POINTERS
 if (!slot.HasExternalPointerHandle()) return;

 DCHECK_EQ(handle, slot.Relaxed_LoadHandle());

 MarkingBarrier* marking_barrier = CurrentMarkingBarrier(host);
 IsolateForPointerCompression isolate(marking_barrier->heap()->isolate());

 ExternalPointerTable& table =
 isolate.GetExternalPointerTableFor(slot.tag_range());
 ExternalPointerTable::Space* space =
 isolate.GetExternalPointerTableSpaceFor(slot.tag_range(), host.address());
 DCHECK(!space->is_internal_read_only_space());

 table.Mark(space, handle, slot.address(), slot.tag_range());

Trusted (indirect) pointers get their own TurboFan opcode, kArchStoreTrustedWithWriteBarrier, because the slot holds a tagged index rather than a pointer.

Setting a map is a write too

Changing an object’s map is a pointer write, and it goes through the barrier like any other - which matters, because the map word is where a forwarding pointer is stored during compaction.

 cpp
 
 
// src/objects/heap-object-set-map-inl.h:100
 set_map_word(value, order);
 Heap::NotifyObjectLayoutChangeDone(this);
#ifndef V8_DISABLE_WRITE_BARRIERS
 if (emit_write_barrier == EmitWriteBarrier::kYes) {
 WriteBarrier::ForValue(this, MaybeObjectSlot(map_slot()), value,
 UPDATE_WRITE_BARRIER);
 } else {

There is also an explicit set_map_safe_transition_no_write_barrier for callers who know the transition is safe.

Trade-offs

What it buys. The generational collector does not have to scan the whole old generation to find its young objects. Incremental and concurrent marking can run without stopping the world. Compacting can move objects without scanning for references.

What it costs.

Every store pays something. Even the fast path is a flag test, and the flag test needs the page header, which is a cache miss away from the object.
The remembered sets are memory. One bit per slot per page, times the number of pages, times the number of remembered set kinds.
The barrier is a correctness hazard. A missed barrier is not a slow path, it is a corrupted heap or a lost object. That is why V8_VERIFY_WRITE_BARRIERS exists and why SKIP_WRITE_BARRIER is a mode the runtime asserts rather than a flag it trusts.
The skipping rules are subtle. “Most recent young allocation” is a property of the allocator, not of the object, and getting it wrong is a use-after-free.

The bottom line

V8’s write barrier is not a “tell the GC that something changed” hook. It is three specific, independently-switchable mechanisms sharing one fast path: remember old-to-new edges so the scavenger can find young objects; maintain the tri-colour invariant during marking so marking can be incremental; and remember slots whose values might move so the compactor can rewrite them.

The deep trick is that the third one does not remember addresses at all. It remembers a bit in a bitmap saying “there is a pointer in this slot”, and the moving object remembers where it went by writing a forwarding pointer into its own map word. Between them the barrier and the object hold all the information, and neither holds the “before” address. The concurrent marker is what the marking half of this exists to feed.

The thing people get wrong

“The write barrier records the old address of the object so the GC can update the reference.” It does not. The barrier records the slot - a bit in a per-page bitmap saying “this field holds a pointer that might need rewriting”. The old address is still sitting in that slot, and the collector reads it out at compaction time, follows the forwarding pointer in the old object’s map word, and overwrites the slot.

That distinction explains why the remembered set can be a bitmap, and why the barrier has to fire on a write even when the value does not change: if the value is on an evacuation candidate page, the collector must know about that slot even if the pointer is identical to what was there before - because the object it points at is about to move.

The other thing people get wrong: “the write barrier is only about the generational GC.” Two of its three jobs only exist during incremental or concurrent marking, and the third only during a compacting GC. The generational part is always on; the expensive part is conditional, which is why the fast path is two flags and a branch.

Five Kinds of String: How V8 Keeps Strings Cheap

Jay Hubbert — Wed, 21 Oct 2026 17:50:00 +0000

TL;DR: A V8 string is not a buffer of characters. It is one of five representations - sequential, cons, sliced, thin or external - tagged in three bits of its instance type. Concatenation builds a rope (a cons string) instead of copying; substring builds a view (a sliced string) instead of copying; internalization builds a pointer (a thin string) instead of copying. The characters are copied only when something actually needs a flat buffer, and String::Flatten is where that copy happens.

The naive way to implement JavaScript strings is to allocate a fresh buffer for every value, copy the characters in, and throw the old buffer away. Every + is an allocation and a memcpy. Every substring is an allocation and a memcpy. Every property lookup by string name is an allocation and a memcpy of the key.

V8 refuses to do that. A string in V8 is a small heap object with a shape, and the shape determines where the characters live - if they live anywhere at all. Five representations cover the cases, and each one exists to answer a specific question cheaply.

The tag: three bits in the instance type

The representation is not a field. It is three bits in the instance type, which means checking it is a mask of an integer that is already in a register:

 cpp
 
 
// src/objects/string.tq:62
bitfield struct StringInstanceType extends uint16 {
 representation: StringRepresentationTag: 3 bit;
 is_one_byte: bool: 1 bit;
 is_uncached: bool: 1 bit;
 is_shared: bool: 1 bit;
 is_not_internalized: bool: 1 bit;
}

The tag itself:

 cpp
 
 
// src/objects/string.tq:54
extern enum StringRepresentationTag extends uint32 {
 kSeqStringTag,
 kConsStringTag,
 kExternalStringTag,
 kSlicedStringTag,
 kThinStringTag
}

The is_one_byte bit is the other half of the story and it is not in the map - it is in the instance type, next to the representation. So the two questions “what kind of string is this?” and “is it Latin-1 or UTF-16?” are answered by a single load of one 16-bit field.

The five representations, as Torque sees them:

 cpp
 
 
// src/objects/string.tq:140
extern class SeqOneByteString extends SeqString {
 const chars[length]: char8;
}

@doNotGenerateCast
@cppObjectLayoutDefinition
extern class SeqTwoByteString extends SeqString {
 const chars[length]: char16;
}

@doNotGenerateCast
@cppObjectLayoutDefinition
extern class SlicedString extends String {
 parent: String;
 offset: Smi;
}

@doNotGenerateCast
@cppObjectLayoutDefinition
extern class ThinString extends String {
 actual: InternalizedString;
}

Note what SeqString has that the others do not: the characters are in the object. SlicedString has a parent and an offset. ThinString has a pointer to the internalized version. ConsString (defined a few lines earlier in the same file) has first and second.

Sequential strings: the only ones with characters in them

A sequential string is the flat case: an object header, a length, and the characters. There are two flavours, one-byte (Latin-1, char8) and two-byte (UTF-16, char16), and the choice is made once, at creation, based on the source data.

The encoding matters a lot: a one-byte string uses half the memory of a two-byte string, and most real-world text - and all of ASCII - fits in one byte. But the choice is sticky. String::IsOneByteRepresentationUnderneath has to walk a cons string’s first half, or a thin string’s target, or a sliced string’s parent, to find the answer:

 cpp
 
 
// src/objects/string.tq:25
 macro IsOneByteRepresentationUnderneath(): bool {
 let string = this;
 while (true) {
 typeswitch (string) {
 case (cons: ConsString): {
 dcheck(cons.IsFlat());
 string = cons.first;
 }
 case (thin: ThinString): {
 // Internalized strings can't change representation.
 dcheck(
 thin.IsOneByteRepresentation() ==
 thin.actual.IsOneByteRepresentation());
 return thin.IsOneByteRepresentation();
 }
 case (slice: SlicedString): {
 string = slice.parent;
 }
 case (str: String): {
 return str.IsOneByteRepresentation();
 }
 }
 }
 VerifiedUnreachable();
 }

The comment “internalized strings can’t change representation” is load-bearing: an internalized string is shared between contexts and threads, so its representation must never change under anyone’s feet.

Cons strings: concatenation without copying

"foo" + "bar" does not copy six characters. It allocates a ConsString - a header, a length, and two pointers - and points them at the two operands:

text

 +------------------+
 | ConsString |
 | first ---------+----> SeqOneByteString "foo"
 | second ---------+----> SeqOneByteString "bar"
 | length = 6
 +------------------+

The consequence is that concatenation is O(1) but the result is a tree. A loop that appends to a string ten thousand times builds a tree of depth logarithmic or linear depending on how the appends are associated, and any operation that needs the actual characters has to walk it.

ConsString::Get is the walk:

 cpp
 
 
// src/objects/string.cc:2135
uint16_t ConsString::Get(
 uint32_t index, const SharedStringAccessGuardIfNeeded& access_guard) const {
 DCHECK(index >= 0 && index < this->length());

 // Check for a flattened cons string
 if (second()->length() == 0) {
 Tagged<String> left = first();
 return left->Get(index);
 }

 Tagged<String> string = Cast<String>(this);

 while (true) {
 if (StringShape(string).IsCons()) {
 Tagged<ConsString> cons_string = Cast<ConsString>(string);
 Tagged<String> left = cons_string->first();
 if (left->length() > index) {
 string = left;
 } else {
 index -= left->length();
 string = cons_string->second();
 }
 } else {
 return string->Get(index, access_guard);
 }
 }

That is str[0] on a cons string: descend the tree, subtracting lengths until you find the leaf that owns the index. Depth is O(log n) for a balanced tree, O(n) for a left-leaning one.

The 13-character threshold

Making a cons string is not free - it is a heap allocation and two write barriers. For short strings the copy is cheaper. V8 picks a threshold of 13 characters:

 cpp
 
 
// src/objects/string.h:1099
 // Minimum length for a cons string.
 static const uint32_t kMinLength = 13;

and the built-in string-add honours it:

 cpp
 
 
// src/builtins/builtins-string-gen.cc:518
 Label non_cons(this, {&var_left, &var_right});
 Label slow(this, Label::kDeferred);
 GotoIf(Uint32LessThan(new_length, Uint32Constant(ConsString::kMinLength)),
 &non_cons);

 result =
 AllocateConsString(new_length, var_left.value(), var_right.value());
 Goto(&done);

 BIND(&non_cons);

 Comment("Full string concatenate");

Below 13 characters, V8 allocates a sequential string and copies. At 13 and above, it allocates a cons string and does not. This is why "a" + "b" and "a" + "b" + "c" are cheap and why s += "x" in a loop eventually becomes expensive: it is not the copy, it is the tree.

Sliced strings: a substring is a view

str.substring(10, 20) does not copy either. A SlicedString holds a pointer to the parent and an offset:

 cpp
 
 
// src/objects/string.tq:152
extern class SlicedString extends String {
 parent: String;
 offset: Smi;
}

The parent stays alive as long as the slice does, which is the price of the view. The offset is a Smi, so it is a tagged 32-bit integer - cheap to add to a base pointer.

Slices have their own 13-character threshold, for the same reason cons strings do - a slice of 3 characters is not worth a heap object plus keeping the parent alive:

 cpp
 
 
// src/objects/string.h:1209
 // Minimum length for a sliced string.
 static const uint32_t kMinLength = 13;

 cpp
 
 
// src/builtins/builtins-string-gen.cc:2164
 // Short slice. Copy instead of slicing.
 GotoIf(IntPtrLessThan(substr_length,
 IntPtrConstant(SlicedString::kMinLength)),
 &next);

There is one more subtlety in the Torque StringToSlice macro: a slice of a slice accumulates offsets rather than nesting, and the accumulated offset is clamped with 32-bit wrapping arithmetic to keep a corrupted offset from reading out of the sandbox:

 cpp
 
 
// src/objects/string.tq:303
 case (s: SlicedString): {
 // Clamp accumulated offsets using 32-bit wrapping arithmetic to prevent
 // out-of-sandbox reads under memory corruption (see b/519768343).
 const slicedOffset: int32 =
 TruncateIntPtrToInt32(Convert<intptr>(s.offset));
 const newOffset: int32 = TruncateIntPtrToInt32(offset) + slicedOffset;
 offset = Convert<intptr>(Unsigned(newOffset));
 string = s.parent;

Thin strings: internalization without copying

When you use a string as a property name, V8 internalizes it - there must be exactly one object per unique name so that property lookups can compare pointers.

If the string can be internalized in place, V8 just changes its map and it becomes an InternalizedString. If it cannot - because it is in shared space, or because its buffer is already in use - the original is turned into a ThinString that points at the internalized copy. The original’s characters stay where they are; the object just becomes a pointer:

 cpp
 
 
// src/objects/string.cc:139
void String::MakeThin(IsolateT* isolate,
 Tagged<InternalizedString> internalized) {
 DisallowGarbageCollection no_gc;
 DCHECK_NE(this, internalized);

 SYNCHRONIZATION_POINT("MakeThinString");

 Tagged<Map> initial_map = map(kAcquireLoad);
 StringShape initial_shape(initial_map);

 DCHECK(!initial_shape.IsThin());

A thin string is, as the C++ header puts it, a “one-part cons string”: the same trick, with one operand.

The problem is that the hash field of a string is where the hash lives, and you cannot have both a hash and a “pointer to the internalized version” in the same 32 bits. V8 solves this with a forwarding table: the hash field stores an index, and a side table maps the index to the internalized string.

 cpp
 
 
// src/objects/string-forwarding-table.h:16
// Mapping from forwarding indices (stored in a string's hash field) to
// internalized strings/external resources.
// The table is used to handle string transitions (temporarily until the next
// full GC, during which actual string transitions happen) that overwrite the
// string buffer. In particular these are Internalization and Externalization.
// The table is organised in "blocks". As writes only append new entries, the
// organisation in blocks allows lock-free writes. We need a lock only for
// growing the table (adding more blocks). When the vector holding the blocks
// needs to grow, we keep a copy of the old vector alive to allow concurrent
// reads while the vector is relocated.
class StringForwardingTable {

The blocks design is what makes it lock-free: writers only ever append, so they never need to take the mutex that the table-growth path holds.

The full GC is where the deferred transitions actually happen: the string’s hash field is overwritten with the real hash and the string becomes a thin string for real. Until then, a lookup of a forwarding index in the table gives you the internalized string.

External strings: characters that live outside the heap

An embedder can hand V8 a pointer to memory it owns and ask for a string that wraps it. That is an ExternalString: the characters are not in the V8 heap at all.

 cpp
 
 
// src/objects/string.h:1257
V8_OBJECT class ExternalString : public UncachedExternalString {
 V8_IT_ABSTRACT;
 V8_IT_NO_AUTO_CHECKER;

 public:
 class BodyDescriptor;

 DECL_VERIFIER(ExternalString)

 inline void InitExternalPointerFields(Isolate* isolate);
 inline void VisitExternalPointers(ObjectVisitor* visitor);

Two details make external strings awkward in a moving GC: the resource pointer and the resource data pointer are ExternalPointers, which live in a separate indirection table so that a moving GC does not have to fix them up; and the string is always allocated in old space and registered with the heap’s external string table, because it must not move:

 cpp
 
 
// src/heap/factory.cc:1534
 DirectHandle<Map> map = resource->IsCacheable()
 ? external_one_byte_string_map()
 : uncached_external_one_byte_string_map();
 Tagged<ExternalOneByteString> external_string =
 Cast<ExternalOneByteString>(New(map, AllocationType::kOld));
 DisallowGarbageCollection no_gc;
 external_string->InitExternalPointerFields(isolate());
 external_string->set_length(static_cast<int>(length));
 external_string->set_raw_hash_field(String::kEmptyHashField);
 external_string->SetResource(isolate(), resource);

 isolate()->heap()->RegisterExternalString(external_string);

The “cacheable” flag decides whether the data pointer is cached inside the string object or re-read from the resource on every access. Caching it is faster; not caching it means the embedder can mutate the buffer underneath V8 and have the change visible.

Why `str.length` is O(1) and `str[0]` might not be

This is the payoff of the whole design, and it falls straight out of it.

length is a field in the string header. Every representation has one, and for a cons string it is the sum of the two halves, maintained at construction. So str.length is a load, on every representation, always.

 cpp
 
 
// src/objects/string.tq:51
 const length: int32;

str[0] is not a load. It is a dispatch:

sequential string: chars[offset] - a load.
sliced string: parent.Get(offset + index) - recurse.
cons string: walk the tree, subtracting lengths.
thin string: actual.Get(index) - one extra hop.

And the first thing most operations do is flatten. String::Flatten in C++ is the fast path plus the slow path:

 cpp
 
 
// src/objects/string-inl.h:956
HandleType<String> String::Flatten(Isolate* isolate, HandleType<T> string,
 AllocationType allocation) {
 DisallowGarbageCollection no_gc; // Unhandlified code.
 Tagged<String> s = *string;
 StringShape shape(s);

 // Shortcut already-flat strings.
 if (V8_LIKELY(shape.IsDirect())) return string;

 if (shape.IsCons()) {
 DCHECK(!HeapLayout::InAnySharedSpace(s));
 Tagged<ConsString> cons = Cast<ConsString>(s);
 if (!cons->IsFlat()) {
 AllowGarbageCollection yes_gc;
 DCHECK_EQ(*string, s);
 HandleType<String> result =
 SlowFlatten(isolate, Cast<ConsString>(string), allocation);
 DCHECK(result->IsFlat());
 DCHECK(string->IsFlat()); // In-place flattened.
 return result;
 }
 s = cons->first();
 shape = StringShape(s);
 }

The flattening is done in place: the cons string is mutated into a degenerate form where first points at the new flat string and second is the empty string. So the copy happens once, and every later access is cheap. The Torque version does the same thing:

 cpp
 
 
// src/objects/string.tq:245
 let flat: String;
 if (cons.map == kConsOneByteStringMap) {
 const allocated = AllocateNonEmptySeqOneByteString(Unsigned(cons.length));
 StringWriteToFlatOneByte(
 cons, (&allocated.chars).GCUnsafeStartPointer(), 0, cons.length);
 flat = allocated;
 } else {
 const allocated = UnsafeCast<SeqTwoByteString>(
 AllocateNonEmptySeqTwoByteString(Unsigned(cons.length)));
 StringWriteToFlatTwoByte(
 cons, (&allocated.chars).GCUnsafeStartPointer(), 0, cons.length);
 flat = allocated;
 }
 cons.first = flat;
 cons.second = kEmptyString;
 return flat;

Note the dispatch on kConsOneByteStringMap - the flattening preserves the one-byte-ness of the original.

The string table

Everything above is about a single string. The string table is where V8 makes sure that two equal strings are the same object, which is what makes property lookup by name a pointer comparison.

The table is an open-addressed hash table with quadratic probing, held outside the V8 heap so that it can be rehashed without moving anything:

 cpp
 
 
// src/objects/string-table.cc:77
// Data holds the actual data of the string table, including capacity and number
// of elements.
//
// It is a variable sized structure, with a "header" followed directly in memory
// by the elements themselves. These are accessed as offsets from the elements_
// field, which itself provides storage for the first element.
//
// The elements themselves are stored as an open-addressed hash table, with
// quadratic probing and Smi 0 and Smi 1 as the empty and deleted sentinels,
// respectively.
class StringTable::Data {

with a minimum capacity of 2048 entries and a load factor of at most 1/4:

 cpp
 
 
// src/objects/string-table.cc:38
 static constexpr int kEntrySize = 1;
 static constexpr int kMaxEmptyFactor = 4;
 static constexpr int kMinCapacity = 2048;

The lookup is StringTable::LookupString, and the first thing it does is flatten:

 cpp
 
 
// src/objects/string-table.cc:369
DirectHandle<InternalizedString> StringTable::LookupString(
 Isolate* isolate, DirectHandle<String> string) {

because you cannot hash a tree. Then it either finds the string already internalized, or resolves a forwarding index, or hashes it and probes:

 cpp
 
 
// src/objects/string-table.cc:403
 uint32_t raw_hash_field = flat_string->raw_hash_field(kAcquireLoad);

 if (String::IsInternalizedForwardingIndex(raw_hash_field)) {
 const int index =
 String::ForwardingIndexValueBits::decode(raw_hash_field);
 result = direct_handle(
 isolate->string_forwarding_table()->GetForwardString(isolate, index),
 isolate);
 } else {

One nice detail: the hasher reports whether the content was entirely one-byte while it was hashing, so the table does not have to scan the string a second time to decide whether a one-byte internalized copy is needed:

 cpp
 
 
// src/objects/string-table.cc:418
 bool one_byte_content = false;
 if (!Name::IsHashFieldComputed(raw_hash_field)) {
 raw_hash_field = flat_string->EnsureRawHash(&one_byte_content);
 } else if (Name::IsIntegerIndex(raw_hash_field)) {
 one_byte_content = true;
 }
 InternalizedStringKey key(flat_string, raw_hash_field, one_byte_content);
 result = LookupKey(isolate, &key);

Trade-offs

What it buys. Concatenation is O(1) instead of O(n). substring is O(1) instead of O(n). Internalization is O(1) instead of O(n). length is always a load. A program that builds large strings by appending never pays for a copy until something actually needs the flat buffer.

What it costs.

The copy is deferred, not avoided. Somebody eventually needs the characters, and then a copy happens - potentially a large one, at an unpredictable moment. String::Flatten allocating a multi-megabyte buffer in the middle of a request is a real failure mode.
Retained parents. A sliced string keeps its parent alive. Slicing a 10 MB string and keeping 3 characters keeps 10 MB alive.
Tree depth. str[0] on a deep cons tree is a walk. V8 mitigates this by flattening eagerly in the interpreter and in the parts of the runtime that need flat content, but the pathology exists for code that only ever indexes.
The forwarding table is a side channel. Every pending internalization costs a table entry and a hash-field encoding, and the transitions are only made real at the next full GC.
External strings escape the heap’s invariants. Their characters can be mutated underneath V8, and their lifetimes are the embedder’s problem.

The bottom line

A V8 string is a tagged union, and the tag is chosen so that the common operation is cheap: concatenation gets a cons string, slicing gets a sliced string, interning gets a thin string, and only genuine data gets a sequential string with the characters inside it.

The two invariants that make it all work: length is always a field, and flattening is done in place so it happens at most once per cons string. The memory model to keep is a string is a handle, not a buffer - and V8 only pays for the buffer when you ask for one.

The thing people get wrong

“Strings are immutable in JavaScript, so V8 can always share their buffers.” No. Immutability is a language guarantee about the characters. V8 still has to represent a string, and it represents it as a pointer to a rope, a slice of a bigger string, or another string entirely. The characters are copied when the rope is flattened, and the copy is not free.

The practical consequences are the ones worth internalising:

Building a string with += in a loop builds a rope, and the rope is flattened at some unpredictable later point. If you know the final length, build it in one go.
str.substring keeps the whole parent alive. If you keep a small piece of a large string, copy it out (str.slice() in some engines, or String(...)) rather than keeping the view.
str.length is cheap, str[0] might not be, and str === other is a pointer comparison only if both sides are internalized - which is why comparing two runtime-built strings is not as cheap as it looks.

The internalized strings the table hands out are exactly what the feedback vector stores: one canonical object per property name, so that the IC can compare pointers instead of characters.

How V8 Gives Every Object a Hidden Class

Jay Hubbert — Wed, 21 Oct 2026 17:20:00 +0000

TL;DR: Every V8 object points at a Map that describes its shape: instance size, property offsets, the descriptor array. Adding a property does not mutate the object - it walks a tree of Maps, one edge per property name, and the new map is shared with every other object that made the same sequence of additions. The transitions are held in weak references, so an unused shape dies with its last user; when a shape has to change underneath live objects, V8 deprecates the transition tree and deoptimizes the code that depended on it.

JavaScript gives you objects you can mutate at any time. obj.x = 1 on an object that never had an x is legal, and legal again on the next line, and legal again a million times in a loop. The specification says nothing about “shape” - it says properties live in an ordinary ordered list.

V8 needs something much more specific than that. Its optimizing compiler emits code like obj.x assuming that x lives at offset 8 of the object and that reading it is just a load. For that assumption to be sound, V8 needs to know, cheaply and exactly, where each property lives. That knowledge lives in a separate heap object - the Map - and the rules for how maps relate to each other live in a transition tree.

The interesting part is not that the map exists. It is that the tree is weak, that it is ordered, and that changing a shape underneath live objects is a deoptimization event rather than a silent fixup.

The same idea carries the inline cache: in unoptimized code, obj.x compares the receiver’s map against an expected map and, if they match, uses a cached offset. The map is the thing being compared.

The Map is not the prototype

The single most common confusion: people call the map a “prototype” or a “class”. It is neither. The prototype is the object you get when you look up a missing property, and it is reachable from any object. The map is the description of an object - its layout - and it is reachable from every object in the heap.

V8 keeps them in separate fields of the map itself, and the field names make the distinction obvious:

 cpp
 
 
// src/objects/map.tq:89
 prototype: JSPrototype;
 constructor_or_back_pointer_or_native_context: Object;

 @if(V8_ENABLE_WEBASSEMBLY) instance_descriptors: DescriptorArray
 |WasmStruct;
 @ifnot(V8_ENABLE_WEBASSEMBLY) instance_descriptors: DescriptorArray;

 // Wasm maps with custom descriptors overload the "dependent_code" field to
 // store their direct supertype map (i.e. their type's canonical RTT).
 @if(V8_ENABLE_WEBASSEMBLY) dependent_code: DependentCode|Map;
 @ifnot(V8_ENABLE_WEBASSEMBLY) dependent_code: DependentCode;

 prototype_validity_cell: Zero|Cell;
 transitions_or_prototype_info: Map|Weak<Map>|TransitionArray|PrototypeInfo|
 PrototypeSharedClosureInfo|Zero;

The prototype lives in prototype. The shape lives in instance_descriptors. The last field is the interesting one: depending on what kind of map this is, that single slot holds either the map’s outgoing transitions (a Map, a Weak<Map> or a TransitionArray) or, for a prototype map, a PrototypeInfo. The header comment in map.h spells out the union:

 cpp
 
 
// src/objects/map.h:250
// +---------------+-------------------------------------------------+
// | TaggedPointer | If Map is a prototype map: |
// | | [prototype_info] |
// | | Else: |
// | | [raw_transitions] |
// +---------------+-------------------------------------------------+

A prototype map is a map that describes an object which is used as a prototype. Such an object is read a lot and written rarely, so V8 optimizes its layout differently - and it needs the extra PrototypeInfo slot, so the transitions have to move out of the way.

What a map actually contains

The map itself is small and packed. map.tq defines three bit-field groups plus a handful of bytes:

 cpp
 
 
// src/objects/map.tq:78
 instance_size_in_words: uint8;
 inobject_properties_start_or_constructor_function_index: uint8;
 used_or_unused_instance_size_in_words: uint8;
 visitor_id: uint8;
 instance_type: InstanceType;
 bit_field: MapBits1;
 bit_field2: MapBits2;
 bit_field3: MapBits3;

bit_field3 is where the interesting bookkeeping lives:

 cpp
 
 
// src/objects/map.tq:28
bitfield struct MapBits3 extends uint32 {
 enum_length: int32: 10 bit;
 number_of_own_descriptors: int32: 10 bit;
 is_prototype_map: bool: 1 bit;
 is_dictionary_map: bool: 1 bit;
 owns_descriptors: bool: 1 bit;
 is_in_retained_map_list: bool: 1 bit;
 is_deprecated: bool: 1 bit;
 is_unstable: bool: 1 bit;
 is_migration_target: bool: 1 bit;
 is_extensible: bool: 1 bit;
 may_have_interesting_properties: bool: 1 bit;
 construction_counter: int32: 3 bit;
}

is_deprecated is the “this shape is stale, stop using it” flag. is_dictionary_map means the object gave up on fast properties and moved to a name dictionary. construction_counter drives in-object slack tracking - the mechanism that decides how much space to reserve inside the object itself for future properties.

The instance_size_in_words byte plus the inobject_properties_start byte are the reason V8 can do obj.x in one load: the map says “the object’s in-object properties start at word 2, x is the third field, so it’s at address this + 8”.

The descriptor array is where the shape lives

The map does not itself store property names. It points at a DescriptorArray, and the layout of that array is documented right in the header:

 cpp
 
 
// src/objects/descriptor-array.h:73
// A DescriptorArray is a custom array that holds instance descriptors.
// It has the following layout:
// Header:
// [16:0 bits]: number_of_all_descriptors (including slack)
// [32:16 bits]: number_of_descriptors
// [64:32 bits]: raw_gc_state (used by GC)
// [kEnumCacheOffset]: enum cache
// Elements:
// [kHeaderSize + 0]: first key (and internalized String)
// [kHeaderSize + 1]: first descriptor details (see PropertyDetails)
// [kHeaderSize + 2]: first value for constants / Tagged<Smi>(1) when not
// used
// Slack:
// [kHeaderSize + number of descriptors * 3]: start of slack
// The "value" fields store either values or field types. A field type is either
// FieldType::None(), FieldType::Any() or a weak reference to a Map. All other
// references are strong.

Three words per property: key, details, value. The “details” word packs the property kind, whether it lives in a field or in the dictionary, whether it is const, and the representation of the value:

 cpp
 
 
// src/objects/property-details.h:97
 enum Kind {
 kNone,
 kSmi,
 kDouble,
 kHeapObject,
 kTagged,
 // This representation is used for WasmObject fields and basically means
 // that the actual field type information must be taken from the Wasm RTT
 // associated with the map.
 kWasmValue,
 kNumRepresentations
 };

kSmi means “this field is known to hold a small integer”, so it can be stored unboxed in the object. That is a layout decision, and it is baked into the map - which means changing a field from kSmi to kDouble is a map change, and possibly a deprecation.

Note that the value slot of a data field holds a FieldType, not a value. FieldType can be Any, None, or a weak reference to another Map whose own field types it inherits. That weak reference is how V8 encodes “this field has the same type as that field over there” without keeping the other map alive.

Adding a property: the transition tree

Here is the core of the whole design. Adding x to an object does not allocate a new object or touch the object’s memory - it looks for (or creates) a child map of the current one:

 cpp
 
 
// src/objects/map.cc:2096
 MaybeHandle<Map> maybe_transition = TransitionsAccessor::SearchTransition(
 isolate, map, *name, PropertyKind::kData, attributes);
 Handle<Map> transition;
 if (maybe_transition.ToHandle(&transition)) {
 InternalIndex descriptor = transition->LastAdded();

 DCHECK_EQ(attributes, transition->instance_descriptors()
 ->GetDetails(descriptor)
 .attributes());

 return UpdateDescriptorForValue(isolate, transition, descriptor, constness,
 value);
 }

If a transition for that name already exists, the existing child map is reused. This is the whole point: the map is not per-object, it is per shape history.

If no transition exists, a new child map is built. Map::CopyWithField does the work:

 cpp
 
 
// src/objects/map.cc:584
MaybeHandle<Map> Map::CopyWithField(Isolate* isolate, DirectHandle<Map> map,
 DirectHandle<Name> name,
 DirectHandle<FieldType> type,
 PropertyAttributes attributes,
 PropertyConstness constness,
 Representation representation,
 TransitionFlag flag) {
 DCHECK(map->instance_descriptors()
 ->Search(*name, map->NumberOfOwnDescriptors())
 .is_not_found());

 // Ensure the descriptor array does not get too big.
 if (map->NumberOfOwnDescriptors() >= kMaxNumberOfDescriptors) {
 return MaybeHandle<Map>();
 }

and the new map is linked into the tree with Map::ConnectTransition, which also handles the “the parent no longer owns its descriptors” bookkeeping:

 cpp
 
 
// src/objects/map.cc:1643
 if (!IsUndefined(parent->GetBackPointer())) {
 parent->set_owns_descriptors(false);
 } else if (!parent->IsDetached(isolate)) {
 // |parent| is initial map and it must not contain descriptors in the
 // descriptors array that do not belong to the map.
 DCHECK_EQ(parent->NumberOfOwnDescriptors(),
 parent->instance_descriptors()->number_of_descriptors());
 }
 if (parent->IsDetached(isolate) && !force_connect) {
 DCHECK(child->IsDetached(isolate));
 if (v8_flags.log_maps) {
 LOG(isolate, MapEvent("Transition", parent, child, "prototype", name));
 }
 } else {
 TransitionsAccessor::Insert(isolate, parent, name, child, transition_kind);

The tree is navigated via a back pointer stored in the map itself, in the slot that otherwise holds the constructor:

 cpp
 
 
// src/objects/map.h:785
 // [back pointer]: points back to the parent map from which a transition
 // leads to this map. The field overlaps with the constructor (see above).
 inline Tagged<HeapObject> GetBackPointer() const;

Map::FindRootMap walks it:

 cpp
 
 
// src/objects/map.cc:773
Tagged<Map> Map::FindRootMap() const {
 DisallowGarbageCollection no_gc;
 Tagged<Map> result = this;
 while (true) {
 Tagged<Map> parent;
 if (!result->TryGetBackPointer(&parent)) {
#if DEBUG
 if (IsJSObjectMap(result)) {
 DCHECK_LE(result->NumberOfOwnDescriptors(),
 result->instance_descriptors(kAcquireLoad)
 ->number_of_descriptors());
 }
#endif
 return result;
 }
 result = parent;
 }
}

Why two `obj.x = 1` sites make two maps

Now the part that surprises people. Because the tree is keyed on name sequences, the shape depends on the order in which properties were added.

text

 {} (initial map)
 |
 +x | +y
 |
 {x}
 |
 +y
 |
 {x,y}

 {} (initial map)
 |
 +y | +x
 |
 {y}
 |
 +x
 |
 {y,x}

{x} and {y} are different maps, and {x,y} and {y,x} are different maps. Two objects with the same set of properties but different creation orders have different maps, and therefore different inline caches, and therefore different optimized code.

Worse: obj.x = 1 at one site and obj.y = 1 at another site produce two branches off the same root. Every call site that assigns a property to a freshly-created object contributes an edge to this tree. In a large application, the tree can grow wide and deep, and each map is a live heap object.

V8’s answer to that is not to prevent the tree from growing but to let it die. Transitions are stored in weak references:

 cpp
 
 
// src/objects/transitions.cc:53
 // If the map doesn't have any transitions at all yet, install the new one.
 if (encoding == kUninitialized || encoding == kMigrationTarget) {
 if (flag == SIMPLE_PROPERTY_TRANSITION) {
 ReplaceTransitions(isolate, map, MakeWeak(*target));
 return;
 }
 // If the flag requires a full TransitionArray, allocate one.
 DirectHandle<TransitionArray> result =
 isolate->factory()->NewTransitionArray(1, 0);
 result->Set(0, *name, MakeWeak(*target));
 ReplaceTransitions(isolate, map, result);
 DCHECK_EQ(kFullTransitionArray, GetEncoding(isolate, *result));
 return;
 }

MakeWeak(*target) is the important bit: the child map is reachable only through a weak reference from the parent. If no object in the heap has that shape any more, the child map is collected and the edge disappears. The transition tree is a cache, self-pruning.

There is a fast path worth noting: a map with exactly one outgoing transition stores it inline in the transitions_or_prototype_info slot as a Weak<Map>, with no TransitionArray allocation at all. The encoding of that slot distinguishes the cases.

Deprecation: when a shape has to change underneath live objects

Some changes cannot be done by finding a different map. If a field that was kSmi needs to hold a double, the object has to be rewritten, not just re-pointed. V8 handles this by deprecating the transition tree rooted at the old map:

 cpp
 
 
// src/objects/map.cc:727
void Map::DeprecateTransitionTreeImpl(Isolate* isolate) {
 if (is_deprecated()) return;
 DisallowGarbageCollection no_gc;
 ReadOnlyRoots roots(isolate);
 TransitionsAccessor transitions(isolate, this);
 transitions.ForEachTransition(
 &no_gc,
 [&](Tagged<Map> map) { map->DeprecateTransitionTreeImpl(isolate); },
 nullptr);
 DCHECK(!IsFunctionTemplateInfo(constructor_or_back_pointer()));
 set_is_deprecated(true);
 if (v8_flags.log_maps) {
 LOG(isolate, MapEvent(no_gc, "Deprecate", this, {}));
 }
 DependentCode::DeoptimizeDependencyGroups<Map>(
 isolate, this, DependentCode::kTransitionGroup);
 NotifyLeafMapLayoutChange(isolate);
}

Two things happen at once. The whole subtree is marked deprecated, so no new objects will adopt those shapes. And DependentCode::DeoptimizeDependencyGroups throws away every piece of optimized code that had baked in the old shape. Objects still holding the old map are migrated lazily, when they are next touched - Map::Update looks for a migration target, and if there isn’t one MapUpdater rewrites the object.

This is why “adding a property changes the shape” is a first-class, observable event in V8, and why Map::TransitionToDataProperty has a special path for “too many properties”:

 cpp
 
 
// src/objects/map.cc:2114
 if (!map->TooManyFastProperties(store_origin)) {
 Representation representation = Object::OptimalRepresentation(*value);
 DirectHandle<FieldType> type =
 Object::OptimalType(*value, isolate, representation);
 maybe_map = Map::CopyWithField(isolate, map, name, type, attributes,
 constness, representation, flag);
 }

and TooManyFastProperties is where the “slow properties” threshold lives:

 cpp
 
 
// src/objects/map-inl.h:317
bool Map::TooManyFastProperties(StoreOrigin store_origin) const {
 if (UnusedPropertyFields() != 0) return false;
 if (store_origin != StoreOrigin::kMaybeKeyed) return false;
 if (is_prototype_map()) return false;
 int limit = std::max(
 {v8_flags.fast_properties_soft_limit.value(), GetInObjectProperties()});
 int external =
 NumberOfFields(ConcurrencyMode::kSynchronous) - GetInObjectProperties();
 return external > limit;
}

Past that limit the object is normalized: it stops being a fast-property object and its properties move into a name dictionary. The map becomes a dictionary map and the whole fast-path story is over for that object. This is why obj[computedKey] = v is a cliff and not a slope.

Prototypes use an entirely different mechanism

Because a prototype can be mutated at any time by code you do not control, the “one shape per object” story does not hold for prototypes. V8 handles prototype mutation with validity cells.

A map that serves as a prototype gets a prototype_validity_cell - a Cell holding a token that means “this prototype chain is still as you saw it”. Optimized code that inlined a property lookup through a prototype holds a reference to that cell; when the prototype changes, the cell is invalidated and the dependent code is deoptimized.

 cpp
 
 
// src/objects/map.cc:2566
 // Ensure the prototype is registered with its own prototypes so its cell
 // will be invalidated when necessary.
 JSObject::LazyRegisterPrototypeUser(validity_cell_holder_map, isolate);

The registration is the interesting part. A prototype needs to know who depends on it, so that it can invalidate them. That is the prototype_users list - a WeakArrayList stored in the PrototypeInfo:

 cpp
 
 
// src/objects/js-objects.cc:5277
 DirectHandle<Map> current_user = user;
 DirectHandle<PrototypeInfo> current_user_info =
 Map::GetOrCreatePrototypeInfo(user, isolate);
 for (PrototypeIterator iter(isolate, user); !iter.IsAtEnd(); iter.Advance()) {
 // Walk up the prototype chain as far as links haven't been registered yet.
 if (current_user_info->registry_slot() != PrototypeInfo::UNREGISTERED) {
 break;
 }

Note the walk: a prototype registers itself as a user of its prototype, recursively. So the user list of A.prototype contains B.prototype if B.prototype.__proto__ === A.prototype, and the invalidation can walk downwards:

 cpp
 
 
// src/objects/js-objects.cc:5423
void InvalidatePrototypeChainsInternal(Tagged<Map> map) {
 // We handle linear prototype chains by looping, and multiple children
 // by recursion, in order to reduce the likelihood of running into stack
 // overflows. So, conceptually, the outer loop iterates the depth of the
 // prototype tree, and the inner loop iterates the breadth of a node.
 Tagged<Map> next_map;
 for (; !map.is_null(); map = next_map, next_map = {}) {
 InvalidateOnePrototypeValidityCellInternal(map);

 Tagged<PrototypeInfo> proto_info;
 if (!map->TryGetPrototypeInfo(&proto_info)) return;
 if (!IsWeakArrayList(proto_info->prototype_users())) {
 return;
 }

This is the mechanism behind Object.prototype.__proto__ changes, Reflect.set on a prototype, and class field initializers that shadow a base class accessor.

Keeping maps alive: the retained map list

We said transitions are weak, so shapes die when unused. But some shapes must survive a GC even if no object currently uses them - for instance because optimized code still references the map, or because a debugger is about to ask about it.

V8’s mechanism for that is a per-context list of retained maps, held weakly but with an age counter:

 cpp
 
 
// src/heap/heap.cc:6526
void Heap::AddRetainedMaps(DirectHandle<NativeContext> context,
 base::Vector<const IndirectHandle<Map>> maps) {

Each entry stores the map weakly plus a “retain for N more GCs” counter (v8_flags.retain_maps_for_n_gc), and the map sets its own is_in_retained_map_list bit so it is not added twice. When the list overflows, CompactRetainedMaps drops the entries whose weak references have cleared.

Trade-offs

What it buys. Property access becomes a single load at a compile-time constant offset. Inline caches become a pointer comparison against a map. Two objects with the same shape share one map and one set of compiled feedback, so a codebase with thousands of Point objects pays for one shape, not thousands.

What it costs.

Memory. Every distinct property-addition sequence is a distinct map, with a descriptor array, a transition array and a back pointer. Programs that build objects in many different orders pay for all of them.
Shape fragility. Adding one property to a hot object can deoptimize a whole function, because the object’s map changed and the old map got deprecated.
The dictionary cliff. Once an object crosses the fast-property limit it is normalized into a name dictionary, and it never comes back.
Weak-reference traffic. Because transitions are weak, every GC has to process and clear them, and a shape that is still in active use has to be re-discovered rather than assumed.
Prototype mutation is not free either. Every prototype gets a validity cell and a user list, and mutating a prototype invalidates the cells of everything below it.

The bottom line

A V8 map is a description of an object, not a prototype and not a class. It answers “how big is this object, where does property x live, and what shape are its elements”. Objects do not own their shape; they point at it.

The shape is reached by walking a transition tree whose edges are property names, so the shape of an object is a function of its history, not of its current property set. That tree is stored with weak references, which makes it self-pruning: a shape nobody uses any more costs nothing. When a shape has to change for objects that already exist, V8 deprecates the tree and deoptimizes the code that assumed the old shape.

The mental model to keep: maps are shared, immutable, and cached; objects are mutable and shareable. The interesting engineering is entirely in deciding when to throw a shared shape away. The feedback vector is where the compiler remembers the shapes it has seen.

The thing people get wrong

“Objects with the same properties have the same hidden class.” No. Objects with the same properties added in the same order share a map. const a = {}; a.x = 1; a.y = 2; and const b = {}; b.y = 2; b.x = 1; produce two different maps and two different inline caches, even though a and b are indistinguishable to Object.keys.

The corollary is the rule of thumb: build objects with all their properties in the same order, in one place, and never add properties conditionally. If you have to build an object whose shape varies, build it through a single factory function so the transition tree stays narrow - or accept the dictionary.

And if you want to see this for yourself, node --allow-natives-syntax plus %DebugPrint(obj) prints the map, its properties, and its prototype, and %HasFastProperties(obj) tells you whether the object is still on the fast path or has already been normalized into a dictionary.

V8 on Opensource internals

Scavenging the Young Generation: How V8 Copies Live Objects in Milliseconds

Two semi-spaces and a swap

The paging allocator

Cheney’s algorithm: the worklists

The forwarding CAS

Promotion: the age mark

The three-way fallback

Pretenuring: allocation-site feedback

Special cases: large objects and strings

The parallel scavenge

Growing and shrinking the young generation

Trade-offs

The bottom line

The thing people get wrong

The Write Barrier: How V8 Knows Where a Moved Object Used to Live

Three jobs, one barrier

The four-tier structure

The fast path: two page flags

The generational barrier: old to new

The marking barrier: keeping the tri-colour invariant

The evacuation barrier: how V8 knows where a moved object used to live

The remembered set is a bitmap, not a list

When the barrier is skipped

How the barrier is generated: CSA and TurboFan

The sandbox: external and trusted pointers

Setting a map is a write too

Trade-offs

The bottom line

The thing people get wrong

Five Kinds of String: How V8 Keeps Strings Cheap

The tag: three bits in the instance type

Sequential strings: the only ones with characters in them

Cons strings: concatenation without copying

The 13-character threshold

Sliced strings: a substring is a view

Thin strings: internalization without copying

External strings: characters that live outside the heap

Why str.length is O(1) and str[0] might not be

The string table

Trade-offs

The bottom line

The thing people get wrong

How V8 Gives Every Object a Hidden Class

The Map is not the prototype

What a map actually contains

The descriptor array is where the shape lives

Adding a property: the transition tree

Why two obj.x = 1 sites make two maps

Deprecation: when a shape has to change underneath live objects

Prototypes use an entirely different mechanism

Keeping maps alive: the retained map list

Trade-offs

The bottom line

The thing people get wrong

Why `str.length` is O(1) and `str[0]` might not be

Why two `obj.x = 1` sites make two maps