Pointer Tagging in V8

V8 uses pointer tagging to efficiently represent different types of values in a single word (pointer-sized). This avoids the overhead of separate type tags for every value, which is especially important for small integers (Smis) and heap object references.

The Tagging Scheme

V8 uses the least significant bits of a pointer-sized word to encode the type of the value.

Small Integers (Smi)

Small integers are encoded directly in the pointer word.

• Tag: The least significant bit is 0.
• Value: The remaining bits represent the integer value (shifted).

Smi Representation Details

The exact representation of Smis depends on the architecture and whether pointer compression is enabled:

• 32-bit architectures and 64-bit architectures with pointer compression:
  • Smis are 31-bit signed integers.
  • They are shifted left by 1 bit.
  • The representation is [31 bits value][0].
• 64-bit architectures without pointer compression:
  • Smis are 32-bit signed integers.
  • They are shifted left by 32 bits.
  • The representation is [32 bits value][32 bits zeros].
  • This allows for fast operations on 64-bit systems where the upper 32 bits can be treated as a 32-bit integer directly in some instructions. Specifically, when loading the value from a field, we can increase the load offset by 4 bytes to load just the 32-bit integer payload directly.
  • Note: This was the default representation on x64 until recently, and is still used if pointer compression is disabled.

Heap Objects

References to objects on the heap are tagged with a non-zero value in the least significant bits.

• Strong Reference: The last two bits are 01.
• Weak Reference: The last two bits are 11.
  • Note on Weakness: The distinction between strong and weak references (bit 1 being 0 vs 1) only exists in the slot on the heap. When a weak pointer is loaded into a register to be used as a normal pointer, the weak bit is typically cleared.
• Constants:
  • kHeapObjectTag = 1
  • kWeakHeapObjectTag = 3
  • kHeapObjectTagMask = 3

Compressed Pointers

When pointer compression is enabled (the default on 64-bit platforms), pointers are stored as 32-bit values. These compressed pointers are relative to the isolate’s cage base address (which is often stored in a dedicated register, e.g., r13 on x64). To decode a compressed pointer to a full 64-bit address, V8 adds it to the cage base.

Compressed pointers are represented in C++ with the Tagged_t type. Tagged_t is uint32_t when pointer compression is enabled, and Address (system-pointer-sized) otherwise.

Forwarding Pointers (GC)

During garbage collection, V8 uses the least significant bits 00 in the object header (MapWord) to indicate a forwarding pointer to the new location of the object. While this looks like a Smi (LSB is 0), it is only valid in the context of the object header during GC.

C++ Representation: Tagged<T>

V8 C++ code uses the Tagged<T> template class (defined in src/objects/tagged.h) to represent tagged pointers. This provides type safety and encapsulates the tagging operations.

• Tagged<Object>: Can represent any tagged value (Smi or HeapObject).
• Tagged<Smi>: Represents a small integer.
• Tagged<HeapObject>: Represents a pointer to any object on the heap.
• Tagged<MyType>: Represents a pointer to a specific heap object type (e.g., Tagged<JSArray>).

The Tagged class handles untagging automatically when dereferencing (e.g., via operator->) or when accessing the raw address via address().

Address Calculation

To get the actual memory address of a heap object from a tagged pointer, the tag must be subtracted:

Address address() const { return this->ptr() - kHeapObjectTag; }

Conversely, to create a tagged pointer from an address, the tag is added:

Tagged(reinterpret_cast<Address>(ptr) + kHeapObjectTag)

For weak pointers, the weak bit is bitwise-ORed:

return Tagged<WeakOf<T>>(value.ptr() | kWeakHeapObjectTag);

See Also

• Pointer Compression for how pointer tagging interacts with pointer compression.