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 (*GCAliveHandleCallback)(Persistent<Object>* handle,

[jochen (gone - plz use gerrit), 2016/03/21 13:31:15]

why not add a new method on PersistentBase?

[Marcel Hlopko, 2016/03/21 14:29:58]

Done.

+                                      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 V8_EXPORT EmbedderHeapTracer {  // NOLINT

[jochen (gone - plz use gerrit), 2016/03/21 13:31:15]

what is // NOLINT needed for?

since the class doesn't have anything outside of this header, I don't think you
need to V8_EXPORT it?

[Marcel Hlopko, 2016/03/21 14:29:58]

Done.

+ public:
+  virtual ~EmbedderHeapTracer() {}

[jochen (gone - plz use gerrit), 2016/03/21 13:31:15]

should this be protected?

+  virtual void TraceWrappablesFrom(Isolate* isolate, Persistent<Object>* value,

[jochen (gone - plz use gerrit), 2016/03/21 13:31:15]

Do you expect this method to return immediately? Do you expect it gets invoked
often?

I wonder whether instead of passing a single persistent, we should pass a vector
of internal fields (because that's essentially what the embedder needs to
identify the object the handle points out).

I'd also call it something like "PutOnMarkingDeque" or similar.

in any case, please document what the method should do.

also, should it be pure virtual?

[Marcel Hlopko, 2016/03/21 14:29:58]

I added the comment, made the method pure virtual. 

Regarding internal fields, sure can do, I just think passing persistent "feels"
nicer and more reusable. I understand though that yagni to be more reusable.

Regarding PutOnMarkingDeque, I changed the name of the callback, I think this is
much better name that what I came with. If you don't like TraceWrappableFrom,
does TraceDependantsOf sound better?

+                                   GCAliveHandleCallback callback) {}
+  /**
+   * 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);
+
+  /**
+   * This function removes the tracer installed by `SetEmbedderHeapTracer`

[jochen (gone - plz use gerrit), 2016/03/21 13:31:15]

please no backticks

you could require the EmbedderHeapTracer* to be passed in again, so you can
check that the embedder is removing the right one.

however, I wonder whether we should allow removing it at all...

[Marcel Hlopko, 2016/03/21 14:29:58]

I will gladly remove the method, I don't think it will ever be used in practice.
I added it only to go with the flow with other GC callbacks (where Remove
methods are actually useful).

I was thinking about introducing NoopEmpedderHeapTracer and setting it as a
default in an isolate, so we don't have to nullcheck each time we access tracer.
But as the code is not too bad with the nullchecks, I haven't done so yet. WDYT?

+   * function.
+   */
+  void UnsetEmbedderHeapTracer();
+
+  /**
    * 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_