Port To Heapobjectlayout

Phase 1: Torque Definition Update (.tq)

Torque needs to know that the layout is now managed by C++, but it still needs the field definitions to generate CSA/Builtin offsets and verification assertions.

1. Locate the class definition in the relevant .tq file.
2. Add the Layout Annotation: Above the extern class definition, add the @cppObjectLayoutDefinition annotation.
3. Preserve the Fields: Do not remove the field definitions; Torque uses them for verification and offset generation.
4. Ensure extern: Ensure the class is declared as extern.

// Example: src/objects/my-object.tq
@cppObjectLayoutDefinition
extern class MyObject extends Struct {
  // KEEP these fields here! Torque needs them for layout verification.
  flags: SmiTagged<MyObjectFlags>;
  value: JSAny|TheHole;
  smi_value: Smi;
  weak_ref: Weak<Map>|Undefined;
}

Phase 2: C++ Header Changes (.h)

Define the explicit memory layout in the C++ header.

1. Include Object Macros: The file must end with #include "src/objects/object-macros.h".
2. Class Definition & Macros: Wrap the class in V8_OBJECT and V8_OBJECT_END.
3. Inheritance: Change the base class to a Layout class (e.g., StructLayout, HeapObjectLayout, TrustedObjectLayout).
4. Declare Fields (Publicly): Define the fields matching the Torque definition, appending _ to their names. Use TaggedMember combined with UnionOf or Weak where appropriate:
   • Unions: TaggedMember<UnionOf<JSAny, Hole>> value_; (Maps to JSAny|TheHole)
   • Weak Unions: TaggedMember<UnionOf<Weak<Map>, Undefined>> weak_ref_;
   • Smis: TaggedMember<Smi> flags_;
   • Doubles: UnalignedDoubleMember float_field_;
   • External Pointers: ExternalPointerMember<kMyTag> ptr_;
   • High-Level Types: For non-tagged fields, prefer storing them as high-level types (e.g., JSDispatchHandle, strongly-typed enums) rather than raw low-level types (like int32_t or uint32_t) whenever conceptually appropriate.
5. Declare Accessors: Add inline getters and setters in the public section. Return types should match the UnionOf types exactly.
   • Tip: For complex UnionOf types, use a public typedef (e.g., using Value = UnionOf<...>;) within the class to improve readability of accessors and field declarations.
   • Note: You can omit PtrComprCageBase getter overloads (e.g. value(cage_base)) as TaggedMember handles decompression natively.
6. Diagnostic Declarations: Add DECL_PRINTER(MyObject) and DECL_VERIFIER(MyObject).
7. Size Constants: If you need size constants (like kAlignedSize), define them as inline constexpr int in the header, outside the V8_OBJECT block to avoid duplicate symbol errors during linking.
8. Variable-Length Tail: For objects with a variable-length suffix (FixedArray-style data), declare the tail as FLEXIBLE_ARRAY_MEMBER(ElementT, name) after the fixed members. Per-index access is then natural via the generated name() accessor combined with TaggedMember's atomic methods, avoiding any need to reach for the static TaggedField<> API. For tagged elements use FLEXIBLE_ARRAY_MEMBER(TaggedMember<JSAny>, objects); for raw embedder slots use FLEXIBLE_ARRAY_MEMBER(Address, slots). Example accessors:

   Tagged<JSAny> MyArray::get(int index) const {
     return objects()[index].Relaxed_Load();
   }
   void MyArray::set(int index, Tagged<JSAny> value, WriteBarrierMode mode) {
     objects()[index].Relaxed_Store(this, value, mode);
   }
   Tagged<JSAny> MyArray::Swap(int index, Tagged<JSAny> value, SeqCstAccessTag) {
     return objects()[index].SeqCst_Swap(this, value);
   }
   

   SizeFor(int length) and OffsetOfElementAt(int index) should be declared inside the class but defined out of line so they can use OFFSET_OF_DATA_START(MyObject) (which references the FAM and is therefore not visible mid-class-body):

   V8_OBJECT class MyObject : public HeapObjectLayout {
     // ...
     static constexpr int SizeFor(int length);
     // ...
     FLEXIBLE_ARRAY_MEMBER(TaggedMember<JSAny>, objects);
   } V8_OBJECT_END;
   
   constexpr int MyObject::SizeFor(int length) {
     return OFFSET_OF_DATA_START(MyObject) + length * kTaggedSize;
   }
   

   The BodyDescriptor typedef can also use OFFSET_OF_DATA_START:

   template <>
   struct ObjectTraits<MyObject> {
     using BodyDescriptor =
         FlexibleBodyDescriptor<OFFSET_OF_DATA_START(MyObject)>;
   };
   

// Example: src/objects/my-object.h
#include "src/objects/struct.h"
#include "src/objects/object-macros.h" // Must be the last include

namespace v8::internal {

#include "torque-generated/src/objects/my-object-tq.inc"

V8_OBJECT class MyObject : public StructLayout {
 public:
  // Accessors
  inline uint32_t flags() const;
  inline void set_flags(uint32_t value);

  inline Tagged<UnionOf<JSAny, Hole>> value() const;
  inline void set_value(Tagged<UnionOf<JSAny, Hole>> value, WriteBarrierMode mode = UPDATE_WRITE_BARRIER);

  inline int smi_value() const;
  inline void set_smi_value(int value);

  inline Tagged<UnionOf<Weak<Map>, Undefined>> weak_ref() const;
  inline void set_weak_ref(Tagged<UnionOf<Weak<Map>, Undefined>> value, WriteBarrierMode mode = UPDATE_WRITE_BARRIER);

  // GC Body Descriptor
  using BodyDescriptor = StructBodyDescriptor;

  // Diagnostics
  DECL_PRINTER(MyObject)
  DECL_VERIFIER(MyObject)

  // Fields (Public for simplified access and Torque asserts)
  TaggedMember<Smi> flags_;
  TaggedMember<UnionOf<JSAny, Hole>> value_;
  TaggedMember<UnionOf<Weak<Map>, Undefined>> weak_ref_;
} V8_OBJECT_END;

}  // namespace v8::internal
#include "src/objects/object-macros-undef.h"

Phase 3: C++ Inline Header Changes (-inl.h)

Implement the accessors using the TaggedMember APIs.

// Example: src/objects/my-object-inl.h
#include "src/objects/my-object.h"
#include "src/objects/objects-inl.h"
#include "src/objects/object-macros.h"

namespace v8::internal {
#include "torque-generated/src/objects/my-object-tq-inl.inc"

int MyObject::flags() const {
  return flags_.load().value();
}
void MyObject::set_flags(int value) {
  flags_.store(this, Smi::FromInt(value));
}

Tagged<UnionOf<JSAny, Hole>> MyObject::value() const {
  return value_.load();
}
void MyObject::set_value(Tagged<UnionOf<JSAny, Hole>> value, WriteBarrierMode mode) {
  value_.store(this, value, mode);
}

Tagged<UnionOf<Weak<Map>, Undefined>> MyObject::weak_ref() const {
  return weak_ref_.load();
}
void MyObject::set_weak_ref(Tagged<UnionOf<Weak<Map>, Undefined>> value, WriteBarrierMode mode) {
  weak_ref_.store(this, value, mode);
}

}  // namespace v8::internal
#include "src/objects/object-macros-undef.h"

Passing this to Write Barriers

If you need to pass the current object to a write barrier macro or function (like CONDITIONAL_WRITE_BARRIER or JS_DISPATCH_HANDLE_WRITE_BARRIER), it might currently expect a Tagged<HeapObject>.

Do not cast this to a Tagged pointer (e.g., Tagged<MyObject>(this)). Instead, follow the same overloading advice as with internal APIs: add an overload to the underlying write barrier function (e.g., WriteBarrier::ForJSDispatchHandle) so that it natively accepts your layout object pointer.

// Incorrect (Casting `this`):
JS_DISPATCH_HANDLE_WRITE_BARRIER(Tagged<MyObject>(this), new_handle);
JS_DISPATCH_HANDLE_WRITE_BARRIER(Tagged<HeapObject>(ptr()), new_handle);

// Correct (Add an overload if necessary, then pass `this` directly):
JS_DISPATCH_HANDLE_WRITE_BARRIER(this, new_handle);

Handling Atomic Fields (Acquire/Release)

If your class previously used atomic macros like DECL_RELAXED_ACCESSORS or DECL_ACQUIRE_GETTER, you can port these directly to TaggedMember which provides built-in support for atomic memory orderings:

• Acquire Load: Use field_.Acquire_Load()
• Release Store: Use field_.Release_Store(this, value, mode)
• Relaxed Load: Use field_.Relaxed_Load()
• Relaxed Store: Use field_.Relaxed_Store(this, value, mode)

// In the .h file
inline Tagged<Object> my_atomic_field(AcquireLoadTag) const;
inline void set_my_atomic_field(Tagged<Object> value, ReleaseStoreTag,
                                WriteBarrierMode mode = UPDATE_WRITE_BARRIER);

// In the -inl.h file
Tagged<Object> MyObject::my_atomic_field(AcquireLoadTag) const {
  return my_atomic_field_.Acquire_Load();
}
void MyObject::set_my_atomic_field(Tagged<Object> value, ReleaseStoreTag,
                                   WriteBarrierMode mode) {
  my_atomic_field_.Release_Store(this, value, mode);
}

Primitive Byte / Word Atomic Fields

Legacy classes often used RELAXED_READ_BYTE_FIELD(obj, kFooOffset) / RELAXED_WRITE_UINT16_FIELD(...) / ACQUIRE_READ_UINT32_FIELD(...) style macros to access primitive uint8_t / uint16_t / uint32_t fields atomically. These macros expand to FIELD_ADDR(obj, offset) which does not exist on HeapObjectLayout subclasses.

Do not add RELAXED_READ_BYTE(&obj->field_) style "field-pointer" macros as a workaround. Instead, declare the field as a std::atomic member of the appropriate width and use the standard .load() / .store() accessors with std::memory_order_*:

// In the V8_OBJECT body: