Introduce phantom weak handles in the API and use them internally for debug info

include/v8.h

 // Copyright 2012 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.
 
 /** \mainpage V8 API Reference Guide
  *
  * V8 is Google's open source JavaScript engine.
  *
  * This set of documents provides reference material generated from the
  * V8 header file, include/v8.h.
@@ skipping 494 matching lines @@
   template<typename P>
   V8_INLINE void SetWeak(
       P* parameter,
       typename WeakCallbackData<T, P>::Callback callback);
 
   template<typename S, typename P>
   V8_INLINE void SetWeak(
       P* parameter,
       typename WeakCallbackData<S, P>::Callback callback);
 
+  // Phantom persistents work like weak persistents, except that the pointer to
+  // the object being collected is not available in the finalization callback.
+  // This enables the garbage collector to collect the object and any objects
+  // it references transitively in one GC cycle.
+  template <typename P>
+  V8_INLINE void SetPhantom(P* parameter,

[ulan, 2014/10/20 14:03:10]

Shouldn't phantom reference be in its own class, separate from PersistentBase to
completely disallow dereferencing?

What prevents the embedder stash a phantom reference p and then just dereference
it in the finalizer like this:
Local<Object> obj = Local<Object>::New(isolate, p)?
and access a potentialy dead object (*obj)

[Erik Corry, 2014/10/20 14:25:32]

I think you want to allow deref before the object dies, otherwise I don't think
it is very useful.
 
I think nothing prevents this, but you can do that with normal weak references
too (not in the finalizer, but after resetting the persistent/global).  But
because it is zapped, it is not until the location is reused for something else
or freed up entirely that you can really run into problems - during the
finalizer you will get the same zapped value that the persistent looks at - just
a Smi.

[Erik Corry, 2014/10/22 13:21:00]

I'll revise my answer to the second part slightly: If you do:

Local<Object> obj = Local<Object>::New(isolate, p)

then you get a new handle, which will keep alive the object, and the callback
will never be called.

On the other hand, internally you can do:

Handle<Object> handle(global_handle.location())

and this gives you a handle that points at the same location as the global
handle (persistent in external terminology).  This can be abused, but this is
not through the API.

+                            typename WeakCallbackData<T, P>::Callback callback);
+
+  template <typename S, typename P>
+  V8_INLINE void SetPhantom(P* parameter,
+                            typename WeakCallbackData<S, P>::Callback callback);
+
   template<typename P>
   V8_INLINE P* ClearWeak();
 
   // TODO(dcarney): remove this.
   V8_INLINE void ClearWeak() { ClearWeak<void>(); }
 
   /**
    * Marks the reference to this object independent. Garbage collector is free
    * to ignore any object groups containing this object. Weak callback for an
    * independent handle should not assume that it will be preceded by a global
@@ skipping 4795 matching lines @@
 
   /**
    * Clears all references to the v8::Platform. This should be invoked after
    * V8 was disposed.
    */
   static void ShutdownPlatform();
 
  private:
   V8();
 
+  enum WeakHandleType { PhantomHandle, NonphantomHandle };
+
   static internal::Object** GlobalizeReference(internal::Isolate* isolate,
                                                internal::Object** handle);
   static internal::Object** CopyPersistent(internal::Object** handle);
   static void DisposeGlobal(internal::Object** global_handle);
   typedef WeakCallbackData<Value, void>::Callback WeakCallback;
-  static void MakeWeak(internal::Object** global_handle,
-                       void* data,
-                       WeakCallback weak_callback);
+  static void MakeWeak(internal::Object** global_handle, void* data,
+                       WeakCallback weak_callback, WeakHandleType phantom);
   static void* ClearWeak(internal::Object** global_handle);
   static void Eternalize(Isolate* isolate,
                          Value* handle,
                          int* index);
   static Local<Value> GetEternal(Isolate* isolate, int index);
 
   template <class T> friend class Handle;
   template <class T> friend class Local;
   template <class T> friend class Eternal;
   template <class T> friend class PersistentBase;
@@ skipping 842 matching lines @@
 }
 
 
 template <class T>
 template <typename S, typename P>
 void PersistentBase<T>::SetWeak(
     P* parameter,
     typename WeakCallbackData<S, P>::Callback callback) {
   TYPE_CHECK(S, T);
   typedef typename WeakCallbackData<Value, void>::Callback Callback;
-  V8::MakeWeak(reinterpret_cast<internal::Object**>(this->val_),
-               parameter,
-               reinterpret_cast<Callback>(callback));
+  V8::MakeWeak(reinterpret_cast<internal::Object**>(this->val_), parameter,
+               reinterpret_cast<Callback>(callback), V8::NonphantomHandle);
 }
 
 
 template <class T>
 template <typename P>
 void PersistentBase<T>::SetWeak(
     P* parameter,
     typename WeakCallbackData<T, P>::Callback callback) {
   SetWeak<T, P>(parameter, callback);
 }
 
 
 template <class T>
-template<typename P>
+template <typename S, typename P>
+void PersistentBase<T>::SetPhantom(
+    P* parameter, typename WeakCallbackData<S, P>::Callback callback) {
+  TYPE_CHECK(S, T);
+  typedef typename WeakCallbackData<Value, void>::Callback Callback;
+  V8::MakeWeak(reinterpret_cast<internal::Object**>(this->val_), parameter,
+               reinterpret_cast<Callback>(callback), V8::PhantomHandle);
+}
+
+
+template <class T>
+template <typename P>
+void PersistentBase<T>::SetPhantom(
+    P* parameter, typename WeakCallbackData<T, P>::Callback callback) {
+  SetPhantom<T, P>(parameter, callback);
+}
+
+
+template <class T>
+template <typename P>
 P* PersistentBase<T>::ClearWeak() {
   return reinterpret_cast<P*>(
     V8::ClearWeak(reinterpret_cast<internal::Object**>(this->val_)));
 }
 
 
 template <class T>
 void PersistentBase<T>::MarkIndependent() {
   typedef internal::Internals I;
   if (this->IsEmpty()) return;
@@ skipping 820 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_