Inline Caches: How V8 Remembers Where a Property Lives

Jay Hubbert — Thu, 22 Oct 2026 16:10:00 +0000

TL;DR: An inline cache is one slot in the feedback vector. It holds a Map and a handler, and the handler is not a pointer - it is a Smi with the kind of load and the field offset bit-packed into it, so the interpreter can compute the property’s address without a single branch on the object kind. When a site sees too many different maps it goes megamorphic and falls back to the stub cache, a two-level hash table keyed on (map, name).

The naive way to read obj.x is to walk the prototype chain looking for a property named x, every single time - a hash lookup per prototype level, per access, forever. The obvious optimisation is to remember the answer: “last time I did this, the receiver was a JSObject with map 0x2ab1c, and x lives at offset 24 in the object.”

That memory is the inline cache, and the design of it is where most of the interesting decisions in V8 live.

What an IC actually is

There is no separate “inline cache object”. An IC is a slot in the feedback vector, and the state machine is a pure function of that slot:

 cpp
 
 
// src/common/globals.h:1920
enum class InlineCacheState {
 // No feedback will be collected.
 NO_FEEDBACK,
 // Has never been executed.
 UNINITIALIZED,
 // Has been executed and only one receiver type has been seen.
 MONOMORPHIC,
 // Check failed due to prototype (or map deprecation).
 RECOMPUTE_HANDLER,
 // Multiple receiver types have been seen.
 POLYMORPHIC,
 // Many DOM receiver types have been seen for the same accessor.
 MEGADOM,
 // Many receiver types have been seen with the same handler.
 HOMOMORPHIC,
 // Many receiver types have been seen.
 MEGAMORPHIC,
 // A generic handler is installed and no extra typefeedback is recorded.
 GENERIC,
};

Nine states, not four. The four everybody quotes - uninitialized, monomorphic, polymorphic, megamorphic - are the common path. The other five are refinements: RECOMPUTE_HANDLER says “recompute this, but do not treat it as evidence of polymorphism”; HOMOMORPHIC means many maps but the same handler, so the handler still works without a per-map dispatch; MEGADOM is the DOM case, where hundreds of element maps funnel into one accessor; GENERIC is the call-IC equivalent of megamorphic; and NO_FEEDBACK means “do not record anything”.

The handler is a Smi, not a pointer

This is the detail that makes V8’s ICs fast. The “handler” that a monomorphic IC stores is not a function pointer and not a heap object. It is a small integer with the kind of load packed into the low four bits:

 cpp
 
 
// src/ic/handler-configuration.h:35
 enum class Kind {
 kElement,
 kElementWithTransition,
 kIndexedString,
 kNormal,
 kGlobal,
 kField,
 kConstantFromPrototype,
 kAccessorFromPrototype,
 kNativeDataProperty,
 kApiGetter,
 kInterceptor,
 kSlow,
 kProxy,
 kNonExistent,
 kModuleExport,
 kGeneric, // Used for keyed loads with "1 map, many property names".
 };
 using KindBits = base::BitField<Kind, 0, 4>;

The remaining bits are kind-specific. A kField handler packs the storage offset in words, whether the field is in-object or out-of-object, whether the field holds a double, and the descriptor index:

 cpp
 
 
// src/ic/handler-configuration.h:96
 //
 // Encoding when KindBits contains kField.
 //
 // +1 here is to cover all possible JSObject header sizes.
 using StorageOffsetInWordsBits =
 LookupOnLookupStartObjectBits::Next<unsigned,
 kDescriptorIndexBitCount + 1>;
 using IsInobjectBits = StorageOffsetInWordsBits::Next<bool, 1>;
 using IsDoubleBits = IsInobjectBits::Next<bool, 1>;

The consequence is that the interpreter’s monomorphic fast path is: load the map from the receiver, compare it against the cached map, and - if it matches - unpack the offset from the Smi and add it to the receiver. No branch on the object kind, no load of the descriptor array, no prototype walk. The only thing that can go wrong is the map comparison.

When the handler cannot be encoded in a Smi - because the property lives on a prototype, or because the chain needs checking - V8 allocates a real LoadHandler object, a DataHandler subclass, and stores it weakly in the second word of the slot.

The handler table

The set of machine-code handlers is a compile-time list, generated by a macro:

 cpp
 
 
// src/builtins/builtins-definitions.h:114
#define LOAD_IC_HANDLER_LIST(V, GENERATE_MACRO) \
 GENERATE_MACRO(V, /*Location*/, /*Representation*/, Uninitialized, \
 /*Index*/) \
 GENERATE_MACRO(V, InObject, NonDouble, Field, /*Index*/) \
 LOAD_IC_IN_OBJECT_FIELD_WITH_INDEX_HANDLER_LIST(V, GENERATE_MACRO) \
 GENERATE_MACRO(V, OutOfObject, NonDouble, Field, /*Index*/) \
 LOAD_IC_OUT_OF_OBJECT_FIELD_WITH_INDEX_HANDLER_LIST(V, GENERATE_MACRO) \
 GENERATE_MACRO(V, /*Location*/, Double, Field, /*Index*/) \
 GENERATE_MACRO(V, /*Location*/, /*Representation*/, ConstantFromPrototype, \
 /*Index*/) \
 GENERATE_MACRO(V, /*Location*/, /*Representation*/, StringLength, /*Index*/) \
 GENERATE_MACRO(V, /*Location*/, /*Representation*/, Generic, /*Index*/)

The /*Location*/ and /*Representation*/ are comments, which is how the macro produces LoadICUninitializedBaseline out of LoadIC##Location##Representation##Kind##Index##Baseline - the location and representation are empty. Expanding the list gives nineteen load IC handlers, in a contiguous range of builtin ids:

 cpp
 
 
// src/builtins/builtins.h:51
#define ADD_ONE(Name, ...) +1
static constexpr int kBuiltinLoadICHandlerCount =
 0 BUILTIN_LOAD_IC_HANDLER_LIST(ADD_ONE);
#undef ADD_ONE

Nineteen handlers covers: uninitialized; in-object and out-of-object, double and non-double fields, at eight and four concrete offsets plus indexed variants; a constant read from a prototype; String.prototype.length; and a generic handler for the rest.

The mapping from a slot’s contents to one of those nineteen is a plain function:

 cpp
 
 
// src/objects/feedback-vector.cc:903
Builtin FeedbackNexus::ic_handler(Tagged<MaybeObject> feedback_extra,
 FeedbackSlotKind kind) {
 if (kind != FeedbackSlotKind::kLoadProperty) return Builtin::kIllegal;
 if (IsSmi(feedback_extra)) {
 int handler = feedback_extra.ToSmi().value();
 LoadHandler::Kind handler_kind = LoadHandler::KindBits::decode(handler);
 // LoadField.
 if (handler_kind == LoadHandler::Kind::kField) {
 int storage_offset =
 LoadHandler::StorageOffsetInWordsBits::decode(handler);
 bool is_inobject = LoadHandler::IsInobjectBits::decode(handler);
 bool is_double = LoadHandler::IsDoubleBits::decode(handler);
 return GetLoadICHandlerForStorageOffset(storage_offset, is_inobject,
 is_double);
 }
 } else {

A kField handler at in-object offset 3 holding a double gets a dedicated builtin - machine code with the offset and the boxing already baked in. That is why there are nineteen and not three: the handler itself is the specialisation.

The state machine on a miss

When the cached map does not match, the IC calls into the runtime, does a full property lookup, computes a new handler, and installs it. The install is a switch over the current state, and the fallthrough comments tell the whole story:

 cpp
 
 
// src/ic/ic.cc:1010
 case UNINITIALIZED: {
 UpdateMonomorphicIC(handler, name);
 if (v8_flags.sparkplug_plus) {
 Builtin ic_handler = FeedbackNexus::ic_handler(*handler, kind());
 MaybePatchCode(ic_handler);
 }
 break;
 }
 case RECOMPUTE_HANDLER:
 case MONOMORPHIC:
 if (IsGlobalIC()) {
 UpdateMonomorphicIC(handler, name);
 break;
 }
 if (TryHealMonomorphicIC(handler)) break;
 if (UpdateOneMapManyNamesIC(name)) break;
 [[fallthrough]];
 case POLYMORPHIC:
 if (UpdatePolymorphicIC(name, handler)) {

The ladder is uninitialized -> monomorphic -> polymorphic -> homomorphic -> megamorphic, and it only ever goes one way. One exception: RECOMPUTE_HANDLER is a state you can return to. When the prototype chain changes under a monomorphic IC, V8 marks the IC for recomputation rather than declaring it polymorphic, because “the prototype changed” is not evidence that the site is polymorphic:

 cpp
 
 
// src/ic/ic.cc:306
void IC::UpdateState(DirectHandle<Object> lookup_start_object,
 DirectHandle<Object> name) {
 if (state() == NO_FEEDBACK) return;
 update_lookup_start_object_map(lookup_start_object);
 if (!IsName(*name)) return;
 if (state() != MONOMORPHIC && state() != POLYMORPHIC) return;
 if (IsNullOrUndefined(*lookup_start_object)) return;
 // Remove the target from the code cache if it became invalid
 // because of changes in the prototype chain to avoid hitting it again.
 if (ShouldRecomputeHandler(Cast<Name>(name))) {
 MarkRecomputeHandler(name);
 }
}

The megamorphic stub cache

When a site has seen too many maps, the IC gives up on per-site caching and installs the megamorphic sentinel in the slot. From then on the lookup goes to a global, shared hash table: the stub cache.

The stub cache is two-level, and the eviction policy is unusual. The header comment in src/ic/stub-cache.h:102 puts it this way: “Unlike a probing strategy (quadratic or otherwise) the update strategy on updates is fairly clear and simple: Any existing entry in the primary cache is moved to the secondary cache, and secondary cache entries are overwritten.”

Primary: 4096 entries. Secondary: 1024. A miss in the primary table promotes the old primary entry into the secondary table and takes over the primary slot. The secondary table is a straight overwrite - it is a victim cache, and it exists so that a recently-displaced entry still hits once.

The two hash functions are deliberately different. The primary uses the name’s precomputed hash field plus a folded map pointer:

 cpp
 
 
// src/ic/stub-cache.cc:32
int StubCache::PrimaryOffset(Tagged<Name> name, Tagged<Map> map) {
 // Compute the hash of the name (use entire hash field).
 uint32_t field = name->RawHash();
 DCHECK(Name::IsHashFieldComputed(field));
 // Using only the low bits in 64-bit mode is unlikely to increase the
 // risk of collision even if the heap is spread over an area larger than
 // 4Gb (and not at all if it isn't).
 uint32_t map_low32bits =
 static_cast<uint32_t>(map.ptr() ^ (map.ptr() >> kPrimaryTableBits));
 uint32_t key = map_low32bits + field;
 return key & ((kPrimaryTableSize - 1) << kCacheIndexShift);
}

The secondary one uses the raw pointers of both, and folds the high bits down so that pointers which differ only in the high bits still spread:

 cpp
 
 
// src/ic/stub-cache.cc:50
int StubCache::SecondaryOffset(Tagged<Name> name, Tagged<Map> old_map) {
 uint32_t name_low32bits = static_cast<uint32_t>(name.ptr());
 uint32_t map_low32bits = static_cast<uint32_t>(old_map.ptr());
 uint32_t key = (map_low32bits + name_low32bits);
 key = key + (key >> kSecondaryTableBits);
 return key & ((kSecondaryTableSize - 1) << kCacheIndexShift);
}

The source comment explains why they must differ: the hash should be “sufficiently different from the primary one in order to avoid collisions for minified code with short names”. After minification a, b and c have near-identical hash fields, so the primary table clumps and the secondary rescues.

The hash is replicated in assembly for every architecture, and the generated code and the C++ must agree bit-for-bit. The kCacheIndexShift trick makes that manageable: the table is indexed in units of 1 << kCacheIndexShift entries, so the entry address is a shift from the base.

The stub cache is also not invalidated when a prototype chain changes. Its own header says so: “The cache does not need explicit invalidation when a prototype chain is modified, since the handlers verify the chain” (src/ic/stub-cache.h:14). The handlers carry their own validity checks. That is the whole trick: the cache is a hint, and the hint knows how to check itself.

Patching the code in place

In the interpreter, nothing is patched - the bytecode handler reads the feedback slot every time. But in Sparkplug, V8’s new baseline tier, the load IC really is a call to a builtin, and the call target is rewritten:

 cpp
 
 
// src/ic/ic.cc:899
void IC::MaybePatchCode(Builtin handler) {
 CHECK(v8_flags.sparkplug_plus);
#ifdef V8_ENABLE_SPARKPLUG_PLUS
 if (handler == Builtin::kIllegal) return;
 Address pc;
 Builtin current_builtin = GetCurrentBaselineBuiltin(&pc);
 if (current_builtin == Builtin::kNoBuiltinId) return;
 if (current_builtin == Builtin::kLoadICGenericBaseline) return;
 Builtin target_builtin = CalculatePatchingTarget(current_builtin, handler);
 if (target_builtin == Builtin::kNoBuiltinId) return;

 Address target = Builtins::EntryOf(target_builtin, isolate_);
 WritableJitAllocation jit_allocation =
 WritableJitAllocation::ForPatchableBaselineJIT(
 pc, Assembler::kCallTargetAddressOffset);
 Assembler::set_target_address_at(pc, kNullAddress, target, &jit_allocation,
 FLUSH_ICACHE_IF_NEEDED);
#endif // V8_ENABLE_SPARKPLUG_PLUS
}

set_target_address_at overwrites the displacement of the call instruction in place and flushes the instruction cache. But look at what CalculatePatchingTarget allows - you can only ever patch towards generic:

 cpp
 
 
// src/ic/ic.cc:851
Builtin CalculatePatchingTarget(Builtin current_builtin, Builtin handler) {
 static_assert(Builtin::kFirstLoadICHandler ==
 Builtin::kLoadICUninitializedBaseline);
 static_assert(Builtin::kLastLoadICHandler == Builtin::kLoadICGenericBaseline);
 // No need to patch when the current and target handlers are the same.
 if (current_builtin == handler) return Builtin::kNoBuiltinId;
 // Uninitialized handler can be patch to any other handlers.
 if (current_builtin == Builtin::kLoadICUninitializedBaseline) {
 return handler;
 }
 // Other handlers are only allowed to be patched to a more generic handler.
 return Builtin::kLoadICGenericBaseline;
}

Once a baseline call site has been specialised to “load field 3, in-object, non-double”, it stays that way until the code is flushed. Patching to a specific handler is only allowed from the uninitialized handler - which is why the “more generic” rule exists: a site specialised for one map must not stay specialised when a second map shows up.

Load versus store

A load IC and a store IC share the same skeleton but not the same handler set, because a store has more to do than a load. A load only needs to find the field. A store might need to add the field, which means transitioning the receiver’s map, which means a transition handler and a validity cell:

The store handler kinds are a different set - kField, kConstField, kAccessorFromPrototype, kApiSetter, kGlobalProxy, kInterceptor, kSlow, kProxy and a kGeneric for keyed stores with “one map, many names” (src/ic/handler-configuration.h:266). kConstField is a store to a field the map says is constant - the handler may throw instead of writing, because the field is read-only.

Store ICs also have their own stub cache. V8 keeps three - one for loads, one for define-own, one for stores - so that a load’s hot entries are not evicted by a store’s churn (src/ic/ic.cc:1118).

The global IC and the property cell

Reading a global variable is a different problem from reading a property. globalThis.x is not a field on an object - it is a slot in the global object’s property dictionary, and the global object is a dictionary-mode object that can be rehashed at any time.

V8’s answer is the PropertyCell: a small heap object holding the value of a global variable and a pointer to the code that depends on its type. When a global load is cached, the IC stores the cell, not the value:

 cpp
 
 
// src/objects/feedback-vector.cc:951
void FeedbackNexus::ConfigurePropertyCellMode(DirectHandle<PropertyCell> cell) {
 DCHECK(IsGlobalICKind(kind()));
 SetFeedback(MakeWeak(*cell), UPDATE_WRITE_BARRIER, UninitializedSentinel(),
 SKIP_WRITE_BARRIER);
}

The cell is stored weakly, so it does not keep the global alive.

And when the global’s type changes - globalThis.x = 1 then globalThis.x = {} - the cell’s DependentCode list is what tells V8 to deoptimize the code that assumed it was a number: the PropertyCellChange lazy deopt reason from the deoptimizer article.

with is the interesting failure case. Inside a with block the lookup goes through a JSGlobalProxy and consults the with object’s properties first, which means an interceptor, so the IC cannot be cached:

 cpp
 
 
// src/ic/ic.cc:1075
 } else if (IsLoadGlobalIC() && lookup->state() == LookupIterator::JSPROXY) {
 // If there is proxy just install the slow stub since we need to call the
 // HasProperty trap for global loads. The ProxyGetProperty builtin doesn't
 // handle this case.
 handler = MaybeObjectHandle(LoadHandler::LoadSlow(isolate()));
 }

LoadHandler::LoadSlow is the “call the runtime” handler. Inside a with, every global read is a runtime call. That is the price of with, and V8 charges it honestly.

The call IC

A call site caches the target function, weakly:

 cpp
 
 
// src/builtins/ic-callable.tq:22
macro TryInitializeAsMonomorphic(
 implicit context: Context)(maybeTarget: JSAny,
 feedbackVector: FeedbackVector,
 slotId: uintptr): void labels TransitionToMegamorphic {
 const targetHeapObject =
 Cast<HeapObject>(maybeTarget) otherwise TransitionToMegamorphic;

 let unwrappedTarget = targetHeapObject;
 while (Is<JSBoundFunction>(unwrappedTarget)) {
 unwrappedTarget =
 UnsafeCast<JSBoundFunction>(unwrappedTarget).bound_target_function;
 }
 const unwrappedTargetJSFunction =
 Cast<JSFunction>(unwrappedTarget) otherwise TransitionToMegamorphic;
 if (!InSameNativeContext(unwrappedTargetJSFunction.context, context)) {
 goto TransitionToMegamorphic;
 }
 StoreWeakReferenceInFeedbackVector(feedbackVector, slotId, targetHeapObject);

Two guards before it will even try: the target must be a JSFunction (not a bound function - it unwraps those - and not a proxy), and it must live in the same native context as the call site. A function from another context means a different Map universe, so it goes megamorphic.

And then the beautiful bit. The call IC does not only cache the target function. It can upgrade to caching the target’s feedback cell:

 cpp
 
 
// src/builtins/ic-callable.tq:132
 // Try transitioning to a feedback cell.
 // Check if {target}s feedback cell matches the {feedbackValue}.
 const target =
 Cast<JSFunction>(maybeTarget) otherwise TransitionToMegamorphic;
 const targetFeedbackCell: FeedbackCell = target.feedback_cell;
 if (TaggedEqual(feedbackValue, targetFeedbackCell)) return;

 // Check if {target} and {feedbackValue} are both JSFunctions with
 // the same feedback vector cell, and that those functions were
 // actually compiled already.
 const feedbackValueJSFunction =
 Cast<JSFunction>(feedbackValue) otherwise TransitionToMegamorphic;
 const feedbackCell: FeedbackCell = feedbackValueJSFunction.feedback_cell;
 if (!TaggedEqual(feedbackCell, targetFeedbackCell))
 goto TransitionToMegamorphic;
 StoreWeakReferenceInFeedbackVector(feedbackVector, slotId, feedbackCell);

Two different closures of the same function literal have different JSFunction objects but the same FeedbackCell - see the feedback vector article. So a call site that alternates between two instances of the same closure factory stays monomorphic, because the IC has learned the thing that matters: “this call always goes to code compiled from the same function literal”. The call count lives in the second word of the same slot.

Trade-offs

What it buys. A property load goes from “hash lookup per prototype level” to “compare one pointer, add one offset”. A call goes from “look up the property call on the function” to “compare one pointer”.

What it costs.

Memory. Every IC site costs one or two words in the feedback vector, and the feedback vector is per closure. The stub cache is a fixed 4096 + 1024 entries per isolate.
Polymorphism is expensive. A site that sees four maps does a linear scan of a WeakFixedArray of (map, handler) pairs on every access. A site that sees five goes megamorphic and gets a hash probe. “Add a fifth shape” is a cliff, not a slope.
The handler is a Smi, so it is bounded. A handler needing more than the Smi bits has to be a heap object, and then the fast path is a load plus a type check plus a dispatch.
The maps are stored weakly. A cached map can be collected at any time, which is why the monomorphic fast path re-checks the map on every access rather than trusting the cache.

The bottom line

An inline cache in V8 is a map plus a bit-packed integer. The map is the key - “this is the shape I saw” - and the integer is the answer, packed so tightly that the interpreter can execute it without a branch on the object kind. The whole design exists to make the common case one pointer compare and one add.

The mental model to keep is that V8’s ICs are not patched into the bytecode in the interpreter; they are patched into the feedback vector, which is a data structure, and which is therefore trivially invalidated, trivially shared, and trivially handed to the optimizing compiler. The specialisation lives in the data, not in the code. Sparkplug is the exception, and even there a specialisation may only become more generic.

The thing people get wrong

“Megamorphic means the IC gave up and every access is now slow.” Not quite. Megamorphic means the site gave up, and the access goes to the stub cache, which is a hash table lookup - a handful of nanoseconds, not a prototype walk. The cost of megamorphism is that you lost the fast path, not that you fell off a cliff.

The other misconception is that a monomorphic IC “remembers the property”. It remembers the map and the offset. If the object is migrated to a different map - which happens every time you add a property, because V8 allocates a fresh map and mutates the object - the IC misses and has to recompute. The faster your objects change shape, the more your inline caches miss. That is the real reason V8 cares so much about map stability, and the reason hidden classes matter more than they look like they should.

Inline-Cache on Opensource internals