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 5343 matching lines @@
  * Memory pressure level for the MemoryPressureNotification.
  * kNone hints V8 that there is no memory pressure.
  * kModerate hints V8 to speed up incremental garbage collection at the cost of
  * of higher latency due to garbage collection pauses.
  * kCritical hints V8 to free memory as soon as possible. Garbage collection
  * pauses at this level will be large.
  */
 enum class MemoryPressureLevel { kNone, kModerate, kCritical };
 
 /**
+ * Structure representing hidden fields of the v8 object. Embedder sets these
+ * fields on wrapper creation to be able to access the object wrapped by the
+ * wrapper.
+ */
+struct WrapperHiddenFields {

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

why not just std::pair<void*,void*>?

[Marcel Hlopko, 2016/03/30 18:51:12]

Because I didn't know it exists :) Done.

+  WrapperHiddenFields(void* wrapper_info_ptr, void* wrapper_source_ptr)
+      : wrapper_info(wrapper_info_ptr), wrapper_source(wrapper_source_ptr) {}
+  void* wrapper_info;
+  void* wrapper_source;
+};
+
+/**
+ * Interface for tracing through the embedder heap. During the v8 garbage
+ * collection, v8 collects hidden fields of all potential wrappers, and at the
+ * end of its marking phase iterates the collection and asks the embedder to
+ * trace through its heap and call Isolate::AddObjectToMarkingDeque for each js
+ * object reachable from the given one.
+ *
+ * Before the first call to the TraceWrappableFrom function v8 will call
+ * TraceRoots. When the v8 garbage collection is finished, v8 will call
+ * ClearTracingMarks.
+ */
+class EmbedderHeapTracer {
+ public:
+  /**
+   * V8 will call this method at the beginning of the gc cycle.
+   */
+  virtual void TraceRoots(Isolate* isolate) {}

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

= 0;

also add an empty line after this one

[Marcel Hlopko, 2016/03/30 18:51:12]

done

+  /**
+   * V8 will call this method with internal fields of a potential wrapper.
+   * Embedder is expected to trace its heap (synchronously) and call
+   * Isolate::AddObjectToMarkingDeque() with all wrappers reachable from the
+   * given one.
+   */
+  virtual void TraceWrappableFrom(Isolate* isolate,
+                                  WrapperHiddenFields internal_fields) {}

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

same here.

why not pass a const std::vector<HiddenFields>& ?

[Marcel Hlopko, 2016/03/30 18:51:12]

Done

+  /**
+   * V8 will call this method at the end of the gc cycle. Allocation is *not*
+   * allowed in the ClearTracingMarks.
+   */
+  virtual void ClearTracingMarks(Isolate* isolate) {}

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

= 0;

[Marcel Hlopko, 2016/03/30 18:51:11]

Done

+
+ protected:
+  virtual ~EmbedderHeapTracer() {}

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

= default;

[Marcel Hlopko, 2016/03/30 18:51:12]

Done

+};
+
+/**
  * 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 {
  public:
   /**
@@ skipping 206 matching lines @@
 
   /**
    * Returns the entered isolate for the current thread or NULL in
    * case there is no current isolate.
    *
    * This method must not be invoked before V8::Initialize() was invoked.
    */
   static Isolate* GetCurrent();
 
   /**
+   * Allows the embedder to add objects to the marking deque of the v8 garbage
+   * collector. Only allowed when the embedder is asked to trace its heap by
+   * EmbedderHeapTracer.
+   */
+  void AddObjectToMarkingDeque(PersistentBase<Object>* handle);

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

why not make this a member of PersistentBase?

[Marcel Hlopko, 2016/03/30 18:51:11]

Done

+
+  /**
    * Custom callback used by embedders to help V8 determine if it should abort
    * when it throws and no internal handler is predicted to catch the
    * exception. If --abort-on-uncaught-exception is used on the command line,
    * then V8 will abort if either:
    * - no custom callback is set.
    * - the custom callback set returns true.
    * Otherwise, the custom callback will not be called and V8 will not abort.
    */
   typedef bool (*AbortOnUncaughtExceptionCallback)(Isolate*);
   void SetAbortOnUncaughtExceptionCallback(
@@ skipping 222 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);
+
+  /**
+   * Gets embedder heap tracer associated with the isolate, or nullptr.
+   */
+  EmbedderHeapTracer* embedder_heap_tracer();

[jochen (gone - plz use gerrit), 2016/03/30 16:44:45]

shouldn't be needed

[Marcel Hlopko, 2016/03/30 18:51:11]

Sure it's not :) Removed.

+
+  /**
    * 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_