Introduce EmbedderHeapTracer

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 5140 matching lines @@
  */
 enum GCCallbackFlags {
   kNoGCCallbackFlags = 0,
   kGCCallbackFlagConstructRetainedObjectInfos = 1 << 1,
   kGCCallbackFlagForced = 1 << 2,
   kGCCallbackFlagSynchronousPhantomCallbackProcessing = 1 << 3,
   kGCCallbackFlagCollectAllAvailableGarbage = 1 << 4,
 };
 
 typedef void (*GCCallback)(GCType type, GCCallbackFlags flags);
+typedef void (*GCPutOnMarkingDequeCallback)(PersistentBase<Object>* handle,
+                                            Isolate* isolate);
 
 typedef void (*InterruptCallback)(Isolate* isolate, void* data);
 
 
 /**
  * Collection of V8 heap information.
  *
  * Instances of this class can be passed to v8::V8::HeapStatistics to
  * get heap statistics from V8.
  */
@@ skipping 172 matching lines @@
 /**
  * Interface for iterating through all the persistent handles in the heap.
  */
 class V8_EXPORT PersistentHandleVisitor {  // NOLINT
  public:
   virtual ~PersistentHandleVisitor() {}
   virtual void VisitPersistentHandle(Persistent<Value>* value,
                                      uint16_t class_id) {}
 };
 
+/**
+ * Interface for tracing through the embedder heap. During the v8 garbage
+ * collection, the embedder is notified that some object he has a reference to
+ * is still alive, and is expected to trace through its heap and call callback
+ * function for each dependent js object.
+ *
+ * After the v8 garbage collection is finished, ClearTracingMarks is called so
+ * the embedder can clear its temporary data.
+ */
+class EmbedderHeapTracer {
+ public:
+  virtual ~EmbedderHeapTracer() {}
+  /**
+   * V8 will call this method with every wrapper. Embedder is expected to call
+   * the provided callback (synchronously) with every dependent wrapper so the
+   * v8 will keep it alive.
+   */
+  virtual void TraceWrappableFrom(Isolate* isolate, Persistent<Object>* value,
+                                  GCPutOnMarkingDequeCallback callback);

[jochen (gone - plz use gerrit), 2016/03/24 14:31:36]

as discussed offline, I'd propose to not add callbacks we don't need yet

+  /**
+   * V8 allocation is *not* allowed in the ClearTracingMarks.
+   */
+  virtual void ClearTracingMarks(Isolate* isolate) {}
+};
 
 /**
  * Isolate represents an isolated instance of the V8 engine.  V8 isolates have
  * completely separate states.  Objects from one isolate must not be used in
  * other isolates.  The embedder can create multiple isolates and use them in
  * parallel in multiple threads.  An isolate can be entered by at most one
  * thread at any given time.  The Locker/Unlocker API must be used to
  * synchronize.
  */
 class V8_EXPORT Isolate {
@@ skipping 442 matching lines @@
   void AddGCPrologueCallback(GCCallback callback,
                              GCType gc_type_filter = kGCTypeAll);
 
   /**
    * This function removes callback which was installed by
    * AddGCPrologueCallback function.
    */
   void RemoveGCPrologueCallback(GCCallback callback);
 
   /**
+   * Sets the embedder heap tracer for the isolate.
+   */
+  void SetEmbedderHeapTracer(EmbedderHeapTracer* tracer);
+
+  /**
    * Enables the host application to receive a notification after a
    * garbage collection. Allocations are allowed in the callback function,
    * but the callback is not re-entrant: if the allocation inside it will
    * trigger the garbage collection, the callback won't be called again.
    * It is possible to specify the GCType filter for your callback. But it is
    * not possible to register the same callback function two times with
    * different GCType filters.
    */
   void AddGCEpilogueCallback(GCCallback callback,
                              GCType gc_type_filter = kGCTypeAll);
@@ skipping 2845 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // INCLUDE_V8_H_