api: Deprecate v8::TracedGlobal

Replacement is v8::TracedReference in combination with v8::Global if a
callback is really needed.

Bug: v8:12603
Change-Id: Iae48fee2e6588a594d430c5f3a71ff0b3e67e5b2
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/3439873Reviewed-by: Dominik Inführ <dinfuehr@chromium.org>
Reviewed-by: Camillo Bruni <cbruni@chromium.org>
Commit-Queue: Michael Lippautz <mlippautz@chromium.org>
Cr-Commit-Position: refs/heads/main@{#78950}

BUILD.bazel

@@ -1144,6 +1144,7 @@ filegroup(
         "src/codegen/unoptimized-compilation-info.h",
         "src/common/assert-scope.cc",
         "src/common/assert-scope.h",
+        "src/common/allow-deprecated.h",
         "src/common/checks.h",
         "src/common/high-allocation-throughput-scope.h",
         "src/common/message-template.h",

BUILD.gn

@@ -2729,6 +2729,7 @@ v8_header_set("v8_internal_headers") {
     "src/codegen/tnode.h",
     "src/codegen/turbo-assembler.h",
     "src/codegen/unoptimized-compilation-info.h",
+    "src/common/allow-deprecated.h",
     "src/common/assert-scope.h",
     "src/common/checks.h",
     "src/common/high-allocation-throughput-scope.h",

include/v8-embedder-heap.h

@@ -51,7 +51,11 @@ class V8_EXPORT EmbedderRootsHandler {
    * being treated as roots.
    */
   virtual bool IsRoot(const v8::TracedReference<v8::Value>& handle) = 0;
-  virtual bool IsRoot(const v8::TracedGlobal<v8::Value>& handle) = 0;
+
+  V8_DEPRECATE_SOON("See v8::TracedGlobal class comment.")
+  virtual bool IsRoot(const v8::TracedGlobal<v8::Value>& handle) {
+    return true;
+  }
 
   /**
    * Used in combination with |IsRoot|. Called by V8 when an
@@ -88,6 +92,7 @@ class V8_EXPORT EmbedderHeapTracer {
   class V8_EXPORT TracedGlobalHandleVisitor {
    public:
     virtual ~TracedGlobalHandleVisitor() = default;
+    V8_DEPRECATE_SOON("See v8::TracedGlobal class comment.")
     virtual void VisitTracedGlobalHandle(const TracedGlobal<Value>& handle) {}
     virtual void VisitTracedReference(const TracedReference<Value>& handle) {}
   };
@@ -189,6 +194,7 @@ class V8_EXPORT EmbedderHeapTracer {
    */
   virtual bool IsRootForNonTracingGC(
       const v8::TracedReference<v8::Value>& handle);
+  V8_DEPRECATE_SOON("See v8::TracedGlobal class comment.")
   virtual bool IsRootForNonTracingGC(const v8::TracedGlobal<v8::Value>& handle);
 
   /**

include/v8-traced-handle.h

@@ -197,6 +197,21 @@ class BasicTracedReference : public TracedReferenceBase {
 /**
  * A traced handle with destructor that clears the handle. For more details see
  * BasicTracedReference.
+ *
+ * This type is being deprecated and embedders are encouraged to use
+ * `v8::TracedReference` in combination with `v8::CppHeap`. If this is not
+ * possible, the following provides feature parity:
+ *
+ * \code
+ * template <typename T>
+ * struct TracedGlobalPolyfill {
+ *   v8::TracedReference<T> traced_reference;
+ *   v8::Global<T> weak_reference_for_callback;
+ * };
+ * \endcode
+ *
+ * In this example, `weak_reference_for_callback` can be used to emulate
+ * `SetFinalizationCallback()`.
  */
 template <typename T>
 class TracedGlobal : public BasicTracedReference<T> {
@@ -211,6 +226,7 @@ class TracedGlobal : public BasicTracedReference<T> {
   /**
    * An empty TracedGlobal without storage cell.
    */
+  V8_DEPRECATE_SOON("See class comment.")
   TracedGlobal() : BasicTracedReference<T>() {}
 
   /**
@@ -220,6 +236,7 @@ class TracedGlobal : public BasicTracedReference<T> {
    * pointing to the same object.
    */
   template <class S>
+  V8_DEPRECATE_SOON("See class comment.")
   TracedGlobal(Isolate* isolate, Local<S> that) : BasicTracedReference<T>() {
     this->val_ =
         this->New(isolate, that.val_, &this->val_,
@@ -490,18 +507,20 @@ V8_INLINE bool operator!=(const v8::Local<U>& lhs,
 
 template <class T>
 template <class S>
-void TracedGlobal<T>::Reset(Isolate* isolate, const Local<S>& other) {
+void TracedReference<T>::Reset(Isolate* isolate, const Local<S>& other) {
   static_assert(std::is_base_of<T, S>::value, "type check");
-  Reset();
+  this->Reset();
   if (other.IsEmpty()) return;
-  this->val_ = this->New(isolate, other.val_, &this->val_,
-                         internal::GlobalHandleDestructionMode::kWithDestructor,
-                         internal::GlobalHandleStoreMode::kAssigningStore);
+  this->SetSlotThreadSafe(
+      this->New(isolate, other.val_, &this->val_,
+                internal::GlobalHandleDestructionMode::kWithoutDestructor,
+                internal::GlobalHandleStoreMode::kAssigningStore));
 }
 
 template <class T>
 template <class S>
-TracedGlobal<T>& TracedGlobal<T>::operator=(TracedGlobal<S>&& rhs) noexcept {
+TracedReference<T>& TracedReference<T>::operator=(
+    TracedReference<S>&& rhs) noexcept {
   static_assert(std::is_base_of<T, S>::value, "type check");
   *this = std::move(rhs.template As<T>());
   return *this;
@@ -509,14 +528,16 @@ TracedGlobal<T>& TracedGlobal<T>::operator=(TracedGlobal<S>&& rhs) noexcept {
 
 template <class T>
 template <class S>
-TracedGlobal<T>& TracedGlobal<T>::operator=(const TracedGlobal<S>& rhs) {
+TracedReference<T>& TracedReference<T>::operator=(
+    const TracedReference<S>& rhs) {
   static_assert(std::is_base_of<T, S>::value, "type check");
   *this = rhs.template As<T>();
   return *this;
 }
 
 template <class T>
-TracedGlobal<T>& TracedGlobal<T>::operator=(TracedGlobal&& rhs) noexcept {
+TracedReference<T>& TracedReference<T>::operator=(
+    TracedReference&& rhs) noexcept {
   if (this != &rhs) {
     internal::MoveTracedGlobalReference(
         reinterpret_cast<internal::Address**>(&rhs.val_),
@@ -526,7 +547,7 @@ TracedGlobal<T>& TracedGlobal<T>::operator=(TracedGlobal&& rhs) noexcept {
 }
 
 template <class T>
-TracedGlobal<T>& TracedGlobal<T>::operator=(const TracedGlobal& rhs) {
+TracedReference<T>& TracedReference<T>::operator=(const TracedReference& rhs) {
   if (this != &rhs) {
     this->Reset();
     if (rhs.val_ != nullptr) {
@@ -538,22 +559,36 @@ TracedGlobal<T>& TracedGlobal<T>::operator=(const TracedGlobal& rhs) {
   return *this;
 }
 
+void TracedReferenceBase::SetWrapperClassId(uint16_t class_id) {
+  using I = internal::Internals;
+  if (IsEmpty()) return;
+  internal::Address* obj = reinterpret_cast<internal::Address*>(val_);
+  uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
+  *reinterpret_cast<uint16_t*>(addr) = class_id;
+}
+
+uint16_t TracedReferenceBase::WrapperClassId() const {
+  using I = internal::Internals;
+  if (IsEmpty()) return 0;
+  internal::Address* obj = reinterpret_cast<internal::Address*>(val_);
+  uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
+  return *reinterpret_cast<uint16_t*>(addr);
+}
+
 template <class T>
 template <class S>
-void TracedReference<T>::Reset(Isolate* isolate, const Local<S>& other) {
+void TracedGlobal<T>::Reset(Isolate* isolate, const Local<S>& other) {
   static_assert(std::is_base_of<T, S>::value, "type check");
-  this->Reset();
+  Reset();
   if (other.IsEmpty()) return;
-  this->SetSlotThreadSafe(
-      this->New(isolate, other.val_, &this->val_,
-                internal::GlobalHandleDestructionMode::kWithoutDestructor,
-                internal::GlobalHandleStoreMode::kAssigningStore));
+  this->val_ = this->New(isolate, other.val_, &this->val_,
+                         internal::GlobalHandleDestructionMode::kWithDestructor,
+                         internal::GlobalHandleStoreMode::kAssigningStore);
 }
 
 template <class T>
 template <class S>
-TracedReference<T>& TracedReference<T>::operator=(
-    TracedReference<S>&& rhs) noexcept {
+TracedGlobal<T>& TracedGlobal<T>::operator=(TracedGlobal<S>&& rhs) noexcept {
   static_assert(std::is_base_of<T, S>::value, "type check");
   *this = std::move(rhs.template As<T>());
   return *this;
@@ -561,16 +596,14 @@ TracedReference<T>& TracedReference<T>::operator=(
 
 template <class T>
 template <class S>
-TracedReference<T>& TracedReference<T>::operator=(
-    const TracedReference<S>& rhs) {
+TracedGlobal<T>& TracedGlobal<T>::operator=(const TracedGlobal<S>& rhs) {
   static_assert(std::is_base_of<T, S>::value, "type check");
   *this = rhs.template As<T>();
   return *this;
 }
 
 template <class T>
-TracedReference<T>& TracedReference<T>::operator=(
-    TracedReference&& rhs) noexcept {
+TracedGlobal<T>& TracedGlobal<T>::operator=(TracedGlobal&& rhs) noexcept {
   if (this != &rhs) {
     internal::MoveTracedGlobalReference(
         reinterpret_cast<internal::Address**>(&rhs.val_),
@@ -580,7 +613,7 @@ TracedReference<T>& TracedReference<T>::operator=(
 }
 
 template <class T>
-TracedReference<T>& TracedReference<T>::operator=(const TracedReference& rhs) {
+TracedGlobal<T>& TracedGlobal<T>::operator=(const TracedGlobal& rhs) {
   if (this != &rhs) {
     this->Reset();
     if (rhs.val_ != nullptr) {
@@ -592,22 +625,6 @@ TracedReference<T>& TracedReference<T>::operator=(const TracedReference& rhs) {
   return *this;
 }
 
-void TracedReferenceBase::SetWrapperClassId(uint16_t class_id) {
-  using I = internal::Internals;
-  if (IsEmpty()) return;
-  internal::Address* obj = reinterpret_cast<internal::Address*>(val_);
-  uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
-  *reinterpret_cast<uint16_t*>(addr) = class_id;
-}
-
-uint16_t TracedReferenceBase::WrapperClassId() const {
-  using I = internal::Internals;
-  if (IsEmpty()) return 0;
-  internal::Address* obj = reinterpret_cast<internal::Address*>(val_);
-  uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
-  return *reinterpret_cast<uint16_t*>(addr);
-}
-
 template <class T>
 void TracedGlobal<T>::SetFinalizationCallback(
     void* parameter, typename WeakCallbackInfo<void>::Callback callback) {

src/common/allow-deprecated.h

+// Copyright 2022 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 V8_COMMON_ALLOW_DEPRECATED_H_
+#define V8_COMMON_ALLOW_DEPRECATED_H_
+
+#if defined(V8_IMMINENT_DEPRECATION_WARNINGS) || \
+    defined(V8_DEPRECATION_WARNINGS)
+
+#if defined(V8_CC_MSVC)
+
+#define START_ALLOW_USE_DEPRECATED() \
+  __pragma(warning(push)) __pragma(warning(disable : 4996))
+
+#define END_ALLOW_USE_DEPRECATED() __pragma(warning(pop))
+
+#else  // !defined(V8_CC_MSVC)
+
+#define START_ALLOW_USE_DEPRECATED() \
+  _Pragma("GCC diagnostic push")     \
+      _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
+
+#define END_ALLOW_USE_DEPRECATED() _Pragma("GCC diagnostic pop")
+
+#endif  // !defined(V8_CC_MSVC)
+
+#else  // !(defined(V8_IMMINENT_DEPRECATION_WARNINGS) ||
+       // defined(V8_DEPRECATION_WARNINGS))
+
+#define START_ALLOW_USE_DEPRECATED()
+#define END_ALLOW_USE_DEPRECATED()
+
+#endif  // !(defined(V8_IMMINENT_DEPRECATION_WARNINGS) ||
+        // defined(V8_DEPRECATION_WARNINGS))
+
+#endif  // V8_COMMON_ALLOW_DEPRECATED_H_

src/handles/global-handles.cc

@@ -12,6 +12,7 @@
 #include "src/api/api-inl.h"
 #include "src/base/compiler-specific.h"
 #include "src/base/sanitizer/asan.h"
+#include "src/common/allow-deprecated.h"
 #include "src/execution/vm-state-inl.h"
 #include "src/heap/base/stack.h"
 #include "src/heap/embedder-tracing.h"
@@ -1322,8 +1323,10 @@ void GlobalHandles::IdentifyWeakUnmodifiedObjects(
       if (is_unmodified(node->location())) {
         v8::Value* value = ToApi<v8::Value>(node->handle());
         if (node->has_destructor()) {
+          START_ALLOW_USE_DEPRECATED()
           node->set_root(handler->IsRoot(
               *reinterpret_cast<v8::TracedGlobal<v8::Value>*>(&value)));
+          END_ALLOW_USE_DEPRECATED()
         } else {
           node->set_root(handler->IsRoot(
               *reinterpret_cast<v8::TracedReference<v8::Value>*>(&value)));
@@ -1709,8 +1712,10 @@ void GlobalHandles::IterateTracedNodes(
     if (node->IsInUse()) {
       v8::Value* value = ToApi<v8::Value>(node->handle());
       if (node->has_destructor()) {
+        START_ALLOW_USE_DEPRECATED()
         visitor->VisitTracedGlobalHandle(
             *reinterpret_cast<v8::TracedGlobal<v8::Value>*>(&value));
+        END_ALLOW_USE_DEPRECATED()
       } else {
         visitor->VisitTracedReference(
             *reinterpret_cast<v8::TracedReference<v8::Value>*>(&value));

src/heap/embedder-tracing.cc

@@ -6,6 +6,7 @@
 
 #include "include/v8-cppgc.h"
 #include "src/base/logging.h"
+#include "src/common/allow-deprecated.h"
 #include "src/handles/global-handles.h"
 #include "src/heap/embedder-tracing-inl.h"
 #include "src/heap/gc-tracer.h"
@@ -220,10 +221,12 @@ bool DefaultEmbedderRootsHandler::IsRoot(
   return !tracer_ || tracer_->IsRootForNonTracingGC(handle);
 }
 
+START_ALLOW_USE_DEPRECATED()
 bool DefaultEmbedderRootsHandler::IsRoot(
     const v8::TracedGlobal<v8::Value>& handle) {
   return !tracer_ || tracer_->IsRootForNonTracingGC(handle);
 }
+END_ALLOW_USE_DEPRECATED()
 
 void DefaultEmbedderRootsHandler::ResetRoot(
     const v8::TracedReference<v8::Value>& handle) {

src/heap/embedder-tracing.h

@@ -8,6 +8,7 @@
 #include "include/v8-cppgc.h"
 #include "include/v8-embedder-heap.h"
 #include "include/v8-traced-handle.h"
+#include "src/common/allow-deprecated.h"
 #include "src/common/globals.h"
 #include "src/execution/isolate.h"
 #include "src/flags/flags.h"
@@ -23,7 +24,11 @@ class V8_EXPORT_PRIVATE DefaultEmbedderRootsHandler final
     : public EmbedderRootsHandler {
  public:
   bool IsRoot(const v8::TracedReference<v8::Value>& handle) final;
+
+  START_ALLOW_USE_DEPRECATED()
   bool IsRoot(const v8::TracedGlobal<v8::Value>& handle) final;
+  END_ALLOW_USE_DEPRECATED()
+
   void ResetRoot(const v8::TracedReference<v8::Value>& handle) final;
 
   void SetTracer(EmbedderHeapTracer* tracer) { tracer_ = tracer; }

test/cctest/heap/test-embedder-tracing.cc

@@ -13,6 +13,7 @@
 #include "include/v8-template.h"
 #include "include/v8-traced-handle.h"
 #include "src/api/api-inl.h"
+#include "src/common/allow-deprecated.h"
 #include "src/handles/global-handles.h"
 #include "src/heap/embedder-tracing.h"
 #include "src/heap/heap-inl.h"
@@ -25,6 +26,8 @@
 #include "test/cctest/cctest.h"
 #include "test/cctest/heap/heap-utils.h"
 
+START_ALLOW_USE_DEPRECATED()
+
 namespace v8 {
 
 namespace internal {
@@ -1327,3 +1330,5 @@ TEST(NotifyEmptyStack) {
 }  // namespace heap
 }  // namespace internal
 }  // namespace v8
+
+END_ALLOW_USE_DEPRECATED()

test/cctest/test-global-handles.cc

@@ -28,6 +28,7 @@
 #include "include/v8-function.h"
 #include "include/v8-locker.h"
 #include "src/api/api-inl.h"
+#include "src/common/allow-deprecated.h"
 #include "src/execution/isolate.h"
 #include "src/handles/global-handles.h"
 #include "src/heap/factory.h"
@@ -36,6 +37,8 @@
 #include "test/cctest/cctest.h"
 #include "test/cctest/heap/heap-utils.h"
 
+START_ALLOW_USE_DEPRECATED()
+
 namespace v8 {
 namespace internal {
 
@@ -727,3 +730,5 @@ TEST(TotalSizeTracedNode) {
 
 }  // namespace internal
 }  // namespace v8
+
+END_ALLOW_USE_DEPRECATED()