[api] Expose new ways to wrap C++ objects with JS wrapper objects

mlippautz · V8 LUCI CQ · commit 549567808376 · 2024-04-03T08:36:17.000Z
JS wrapper objects are generally constructed via ObjectTemplate. Such objects can now be constructed with 0 embedder fields and use the newly introduced Wrap/Unwrap methods to set and get the corresponding C++ pointers. Internally, these will use a CppHeapPointer field and dedicated external pointer table. Bug: chromium:328117814 Change-Id: I9cb79a86ccdca8d185eaf79efffb16051dd75dc0 Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/5401858 Reviewed-by: Samuel Groß <saelo@chromium.org> Reviewed-by: Toon Verwaest <verwaest@chromium.org> Commit-Queue: Michael Lippautz <mlippautz@chromium.org> Cr-Commit-Position: refs/heads/main@{#93129}
diff --git a/BUILD.bazel b/BUILD.bazel
@@ -653,6 +653,7 @@ filegroup(
         "include/v8-promise.h",
         "include/v8-proxy.h",
         "include/v8-regexp.h",
+        "include/v8-sandbox.h",
         "include/v8-script.h",
         "include/v8-snapshot.h",
         "include/v8-statistics.h",
diff --git a/BUILD.gn b/BUILD.gn
@@ -3081,6 +3081,7 @@ v8_header_set("v8_headers") {
     "include/v8-promise.h",
     "include/v8-proxy.h",
     "include/v8-regexp.h",
+    "include/v8-sandbox.h",
     "include/v8-script.h",
     "include/v8-snapshot.h",
     "include/v8-statistics.h",
diff --git a/include/v8-object.h b/include/v8-object.h
@@ -5,10 +5,12 @@
 #ifndef INCLUDE_V8_OBJECT_H_
 #define INCLUDE_V8_OBJECT_H_
 
+#include "v8-internal.h"           // NOLINT(build/include_directory)
 #include "v8-local-handle.h"       // NOLINT(build/include_directory)
 #include "v8-maybe.h"              // NOLINT(build/include_directory)
 #include "v8-persistent-handle.h"  // NOLINT(build/include_directory)
 #include "v8-primitive.h"          // NOLINT(build/include_directory)
+#include "v8-sandbox.h"            // NOLINT(build/include_directory)
 #include "v8-traced-handle.h"      // NOLINT(build/include_directory)
 #include "v8-value.h"              // NOLINT(build/include_directory)
 #include "v8config.h"              // NOLINT(build/include_directory)
@@ -528,7 +530,50 @@ class V8_EXPORT Object : public Value {
                                          void* values[]);
 
   /**
-   * HasOwnProperty() is like JavaScript's Object.prototype.hasOwnProperty().
+   * Unwraps a JS wrapper object.
+   *
+   * \param tag The tag for retrieving the wrappable instance. Must match the
+   * tag that has been used for a previous `Wrap()` operation.
+   * \param isolate The Isolate for the `wrapper` object.
+   * \param wrapper The JS wrapper object that should be unwrapped.
+   * \returns the C++ wrappable instance, or nullptr if the JS object has never
+   * been wrapped.
+   */
+  template <CppHeapPointerTag tag, typename T = void>
+  static V8_INLINE T* Unwrap(v8::Isolate* isolate,
+                             const v8::Local<v8::Object>& wrapper);
+  template <CppHeapPointerTag tag, typename T = void>
+  static V8_INLINE T* Unwrap(v8::Isolate* isolate,
+                             const PersistentBase<Object>& wrapper);
+  template <CppHeapPointerTag tag, typename T = void>
+  static V8_INLINE T* Unwrap(v8::Isolate* isolate,
+                             const BasicTracedReference<Object>& wrapper);
+
+  /**
+   * Wraps a JS wrapper with a C++ instance.
+   *
+   * \param tag The pointer tag that should be used for storing this object.
+   * Future `Unwrap()` operations must provide a matching tag.
+   * \param isolate The Isolate for the `wrapper` object.
+   * \param wrapper The JS wrapper object.
+   * \param wrappable The C++ object instance that is wrapped by the JS object.
+   */
+  template <CppHeapPointerTag tag>
+  static V8_INLINE void Wrap(v8::Isolate* isolate,
+                             const v8::Local<v8::Object>& wrapper,
+                             void* wrappable);
+  template <CppHeapPointerTag tag>
+  static V8_INLINE void Wrap(v8::Isolate* isolate,
+                             const PersistentBase<Object>& wrapper,
+                             void* wrappable);
+  template <CppHeapPointerTag tag>
+  static V8_INLINE void Wrap(v8::Isolate* isolate,
+                             const BasicTracedReference<Object>& wrapper,
+                             void* wrappable);
+
+  /**
+   * HasOwnProperty() is like JavaScript's
+   * Object.prototype.hasOwnProperty().
    *
    * See also v8::Object::Has() and v8::Object::HasRealNamedProperty().
    */
@@ -731,6 +776,11 @@ class V8_EXPORT Object : public Value {
   bool IsCodeLike(Isolate* isolate) const;
 
  private:
+  static void* Unwrap(v8::Isolate* isolate, internal::Address wrapper_obj,
+                      CppHeapPointerTag tag);
+  static void Wrap(v8::Isolate* isolate, internal::Address wrapper_obj,
+                   CppHeapPointerTag tag, void* wrappable);
+
   Object();
   static void CheckCast(Value* obj);
   Local<Data> SlowGetInternalField(int index);
@@ -810,6 +860,73 @@ void* Object::GetAlignedPointerFromInternalField(int index) {
   return SlowGetAlignedPointerFromInternalField(index);
 }
 
+// static
+template <CppHeapPointerTag tag, typename T>
+T* Object::Unwrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper) {
+  auto obj = internal::ValueHelper::ValueAsAddress(*wrapper);
+#if !defined(V8_ENABLE_CHECKS)
+  return internal::ReadCppHeapPointerField<tag, T>(
+      isolate, obj, internal::Internals::kJSObjectHeaderSize);
+#else   // defined(V8_ENABLE_CHECKS)
+  return reinterpret_cast<T*>(Unwrap(isolate, obj, tag));
+#endif  // defined(V8_ENABLE_CHECKS)
+}
+
+// static
+template <CppHeapPointerTag tag, typename T>
+T* Object::Unwrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper) {
+  auto obj =
+      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
+#if !defined(V8_ENABLE_CHECKS)
+  return internal::ReadCppHeapPointerField<tag, T>(
+      isolate, obj, internal::Internals::kJSObjectHeaderSize);
+#else   // defined(V8_ENABLE_CHECKS)
+
+  return reinterpret_cast<T*>(Unwrap(isolate, obj, tag));
+#endif  // defined(V8_ENABLE_CHECKS)
+}
+
+// static
+template <CppHeapPointerTag tag, typename T>
+T* Object::Unwrap(v8::Isolate* isolate,
+                  const BasicTracedReference<Object>& wrapper) {
+  auto obj =
+      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
+#if !defined(V8_ENABLE_CHECKS)
+  return internal::ReadCppHeapPointerField<tag, T>(
+      isolate, obj, internal::Internals::kJSObjectHeaderSize);
+#else   // defined(V8_ENABLE_CHECKS)
+  return reinterpret_cast<T*>(Unwrap(isolate, obj, tag));
+#endif  // defined(V8_ENABLE_CHECKS)
+}
+
+// static
+template <CppHeapPointerTag tag>
+void Object::Wrap(v8::Isolate* isolate, const v8::Local<v8::Object>& wrapper,
+                  void* wrappable) {
+  auto obj = internal::ValueHelper::ValueAsAddress(*wrapper);
+  Wrap(isolate, obj, tag, wrappable);
+}
+
+// static
+template <CppHeapPointerTag tag>
+void Object::Wrap(v8::Isolate* isolate, const PersistentBase<Object>& wrapper,
+                  void* wrappable) {
+  auto obj =
+      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
+  Wrap(isolate, obj, tag, wrappable);
+}
+
+// static
+template <CppHeapPointerTag tag>
+void Object::Wrap(v8::Isolate* isolate,
+                  const BasicTracedReference<Object>& wrapper,
+                  void* wrappable) {
+  auto obj =
+      internal::ValueHelper::ValueAsAddress(wrapper.template value<Object>());
+  Wrap(isolate, obj, tag, wrappable);
+}
+
 Private* Private::Cast(Data* data) {
 #ifdef V8_ENABLE_CHECKS
   CheckCast(data);
diff --git a/include/v8-sandbox.h b/include/v8-sandbox.h
@@ -0,0 +1,63 @@
+// Copyright 2024 the V8 project authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef INCLUDE_V8_SANDBOX_H_
+#define INCLUDE_V8_SANDBOX_H_
+
+#include <cstdint>
+
+#include "v8-internal.h"  // NOLINT(build/include_directory)
+#include "v8config.h"     // NOLINT(build/include_directory)
+
+namespace v8 {
+
+/**
+ * A pointer tag used for wrapping and unwrapping `CppHeap` pointers as used
+ * with JS API wrapper objects that rely on `v8::Object::Wrap()` and
+ * `v8::Object::Unwrap()`.
+ */
+enum class CppHeapPointerTag : uint64_t {
+  kDefaultTag = internal::ExternalPointerTag::kExternalObjectValueTag,
+};
+
+namespace internal {
+
+#ifdef V8_COMPRESS_POINTERS
+V8_INLINE static Address* GetCppHeapPointerTableBase(v8::Isolate* isolate) {
+  Address addr = reinterpret_cast<Address>(isolate) +
+                 Internals::kIsolateCppHeapPointerTableAddressOffset +
+                 Internals::kExternalPointerTableBasePointerOffset;
+  return *reinterpret_cast<Address**>(addr);
+}
+#endif  // V8_COMPRESS_POINTERS
+
+template <CppHeapPointerTag tag, typename T>
+V8_INLINE static T* ReadCppHeapPointerField(v8::Isolate* isolate,
+                                            Address heap_object_ptr,
+                                            int offset) {
+#ifdef V8_COMPRESS_POINTERS
+  static_assert(tag != static_cast<CppHeapPointerTag>(kExternalPointerNullTag));
+  // See src/sandbox/external-pointer-table-inl.h. Logic duplicated here so
+  // it can be inlined and doesn't require an additional call.
+  const CppHeapPointerHandle handle =
+      Internals::ReadRawField<CppHeapPointerHandle>(heap_object_ptr, offset);
+  if (handle == 0) {
+    return reinterpret_cast<T*>(kNullAddress);
+  }
+  const uint32_t index = handle >> kExternalPointerIndexShift;
+  const Address* table = GetCppHeapPointerTableBase(isolate);
+  const std::atomic<Address>* ptr =
+      reinterpret_cast<const std::atomic<Address>*>(&table[index]);
+  Address entry = std::atomic_load_explicit(ptr, std::memory_order_relaxed);
+  return reinterpret_cast<T*>(entry & ~static_cast<uint64_t>(tag));
+#else   // !V8_COMPRESS_POINTERS
+  return reinterpret_cast<T*>(
+      Internals::ReadRawField<Address>(heap_object_ptr, offset));
+#endif  // !V8_COMPRESS_POINTERS
+}
+
+}  // namespace internal
+}  // namespace v8
+
+#endif  // INCLUDE_V8_SANDBOX_H_
diff --git a/src/api/api.cc b/src/api/api.cc
@@ -6298,6 +6298,24 @@ void v8::Object::SetAlignedPointerInInternalFields(int argc, int indices[],
                                                             values);
 }
 
+// static
+void* v8::Object::Unwrap(v8::Isolate* isolate, i::Address wrapper_obj,
+                         CppHeapPointerTag tag) {
+  return i::JSApiWrapper(i::JSObject::cast(i::Tagged<i::Object>(
+                             reinterpret_cast<i::Address>(wrapper_obj))))
+      .GetCppHeapWrappable(reinterpret_cast<i::Isolate*>(isolate),
+                           static_cast<i::ExternalPointerTag>(tag));
+}
+
+// static
+void v8::Object::Wrap(v8::Isolate* isolate, i::Address wrapper_obj,
+                      CppHeapPointerTag tag, void* wrappable) {
+  return i::JSApiWrapper(i::JSObject::cast(i::Tagged<i::Object>(
+                             reinterpret_cast<i::Address>(wrapper_obj))))
+      .SetCppHeapWrappable(reinterpret_cast<i::Isolate*>(isolate), wrappable,
+                           static_cast<i::ExternalPointerTag>(tag));
+}
+
 // --- E n v i r o n m e n t ---
 
 void v8::V8::InitializePlatform(Platform* platform) {
diff --git a/src/objects/heap-object.h b/src/objects/heap-object.h
@@ -311,6 +311,9 @@ class HeapObject : public TaggedImpl<HeapObjectReferenceType::STRONG, Address> {
   template <ExternalPointerTag tag>
   inline Address TryReadCppHeapPointerField(
       size_t offset, IsolateForPointerCompression isolate) const;
+  inline Address TryReadCppHeapPointerField(
+      size_t offset, IsolateForPointerCompression isolate,
+      ExternalPointerTag tag) const;
   template <ExternalPointerTag tag>
   inline void WriteExternalPointerField(size_t offset,
                                         IsolateForSandbox isolate,
@@ -326,6 +329,9 @@ class HeapObject : public TaggedImpl<HeapObjectReferenceType::STRONG, Address> {
   template <ExternalPointerTag tag>
   inline void WriteLazilyInitializedCppHeapPointerField(
       size_t offset, IsolateForPointerCompression isolate, Address value);
+  inline void WriteLazilyInitializedCppHeapPointerField(
+      size_t offset, IsolateForPointerCompression isolate, Address value,
+      ExternalPointerTag tag);
 
   //
   // Indirect pointers.
diff --git a/src/objects/js-objects-inl.h b/src/objects/js-objects-inl.h
@@ -632,6 +632,12 @@ void* JSApiWrapper::GetCppHeapWrappable(
       kCppHeapWrappableOffset, isolate));
 }
 
+void* JSApiWrapper::GetCppHeapWrappable(IsolateForPointerCompression isolate,
+                                        ExternalPointerTag tag) const {
+  return reinterpret_cast<void*>(object_->TryReadCppHeapPointerField(
+      kCppHeapWrappableOffset, isolate, tag));
+}
+
 template <ExternalPointerTag tag>
 void JSApiWrapper::SetCppHeapWrappable(IsolateForPointerCompression isolate,
                                        void* instance) {
@@ -646,6 +652,19 @@ void JSApiWrapper::SetCppHeapWrappable(IsolateForPointerCompression isolate,
   WriteBarrier::MarkingFromCppHeapWrappable(object_, instance);
 }
 
+void JSApiWrapper::SetCppHeapWrappable(IsolateForPointerCompression isolate,
+                                       void* instance, ExternalPointerTag tag) {
+  if (instance == nullptr) {
+    object_->ResetLazilyInitializedCppHeapPointerField(
+        JSAPIObjectWithEmbedderSlots::kCppHeapWrappableOffset);
+    return;
+  }
+  object_->WriteLazilyInitializedCppHeapPointerField(
+      JSAPIObjectWithEmbedderSlots::kCppHeapWrappableOffset, isolate,
+      reinterpret_cast<Address>(instance), tag);
+  WriteBarrier::MarkingFromCppHeapWrappable(object_, instance);
+}
+
 bool JSMessageObject::DidEnsureSourcePositionsAvailable() const {
   return shared_info() == Smi::zero();
 }
diff --git a/src/objects/js-objects.h b/src/objects/js-objects.h
@@ -1028,9 +1028,13 @@ class JSApiWrapper {
   template <ExternalPointerTag tag>
   V8_INLINE void SetCppHeapWrappable(IsolateForPointerCompression isolate,
                                      void*);
+  V8_INLINE void SetCppHeapWrappable(IsolateForPointerCompression isolate,
+                                     void*, ExternalPointerTag tag);
   template <ExternalPointerTag tag>
   V8_INLINE void* GetCppHeapWrappable(
       IsolateForPointerCompression isolate) const;
+  V8_INLINE void* GetCppHeapWrappable(IsolateForPointerCompression isolate,
+                                      ExternalPointerTag tag) const;
 
  private:
   static_assert(JSAPIObjectWithEmbedderSlots::kCppHeapWrappableOffset ==
diff --git a/src/objects/objects-inl.h b/src/objects/objects-inl.h
@@ -792,6 +792,12 @@ Address HeapObject::TryReadCppHeapPointerField(
   return i::TryReadCppHeapPointerField<tag>(field_address(offset), isolate);
 }
 
+Address HeapObject::TryReadCppHeapPointerField(
+    size_t offset, IsolateForPointerCompression isolate,
+    ExternalPointerTag tag) const {
+  return i::TryReadCppHeapPointerField(field_address(offset), isolate, tag);
+}
+
 template <ExternalPointerTag tag>
 void HeapObject::WriteExternalPointerField(size_t offset,
                                            IsolateForSandbox isolate,
@@ -821,6 +827,13 @@ void HeapObject::WriteLazilyInitializedCppHeapPointerField(
                                                     isolate, value);
 }
 
+void HeapObject::WriteLazilyInitializedCppHeapPointerField(
+    size_t offset, IsolateForPointerCompression isolate, Address value,
+    ExternalPointerTag tag) {
+  i::WriteLazilyInitializedCppHeapPointerField(field_address(offset), isolate,
+                                               value, tag);
+}
+
 void HeapObject::InitSelfIndirectPointerField(size_t offset,
                                               IsolateForSandbox isolate) {
   DCHECK(IsExposedTrustedObject(*this));
diff --git a/src/sandbox/external-pointer-inl.h b/src/sandbox/external-pointer-inl.h
diff --git a/test/benchmarks/cpp/bindings.cc b/test/benchmarks/cpp/bindings.cc
