Add an interface for an embedder to provide information about native

include/v8-profiler.h

Index: include/v8-profiler.h
diff --git a/include/v8-profiler.h b/include/v8-profiler.h
index 675a229854ef086f617fae15823f2af8a6da4725..d466d5e9e768a8117b2c9b406b164f7c323dce33 100644
--- a/include/v8-profiler.h
+++ b/include/v8-profiler.h
@@ -245,14 +245,15 @@ class V8EXPORT HeapGraphPath {
 class V8EXPORT HeapGraphNode {
  public:
   enum Type {
-    kHidden = 0,     // Hidden node, may be filtered when shown to user.
-    kArray = 1,      // An array of elements.
-    kString = 2,     // A string.
-    kObject = 3,     // A JS object (except for arrays and strings).
-    kCode = 4,       // Compiled code.
-    kClosure = 5,    // Function closure.
-    kRegExp = 6,     // RegExp.
-    kHeapNumber = 7  // Number stored in the heap.
+    kHidden = 0,      // Hidden node, may be filtered when shown to user.
+    kArray = 1,       // An array of elements.
+    kString = 2,      // A string.
+    kObject = 3,      // A JS object (except for arrays and strings).
+    kCode = 4,        // Compiled code.
+    kClosure = 5,     // Function closure.
+    kRegExp = 6,      // RegExp.
+    kHeapNumber = 7,  // Number stored in the heap.
+    kNative = 8       // Native object (not from V8 heap).
   };
 
   /** Returns node type (see HeapGraphNode::Type). */
@@ -392,11 +393,22 @@ class V8EXPORT HeapSnapshot {
 };
 
 
+class RetainedObjectInfo;
+
 /**
  * Interface for controlling heap profiling.
  */
 class V8EXPORT HeapProfiler {
  public:
+  /**
+   * Callback function invoked for obtaining RetainedObjectInfo for
+   * the given JavaScript wrapper object. It is prohibited to enter V8
+   * while the callback is running: only getters on the handle and
+   * GetPointerFromInternalField on the objects are allowed.
+   */
+  typedef RetainedObjectInfo* (*WrapperInfoCallback)
+      (uint16_t class_id, Handle<Value> wrapper);
+
   /** Returns the number of snapshots taken. */
   static int GetSnapshotsCount();
 
@@ -414,6 +426,81 @@ class V8EXPORT HeapProfiler {
       Handle<String> title,
       HeapSnapshot::Type type = HeapSnapshot::kFull,
       ActivityControl* control = NULL);
+
+  /** Binds a callback to embedder's class ID. */
+  static void DefineWrapperClass(
+      uint16_t class_id,
+      WrapperInfoCallback callback);
+
+  /**
+   * Default value of persistent handle class ID. Must not be used to
+   * define a class. Can be used to reset a class of a persistent
+   * handle.
+   */
+  static const uint16_t kPersistentHandleNoClassId = 0;
+};
+
+
+/**
+ * Interface for providing information about embedder's objects
+ * held by global handles. This information is reported in two ways:
+ *
+ *  1. When calling AddObjectGroup, an embedder may pass
+ *     RetainedObjectInfo instance describing the group.  To collect
+ *     this information while taking a heap snapshot, V8 calls GC
+ *     prologue and epilogue callbacks.
+ *
+ *  2. When a heap snapshot is collected, V8 additionally
+ *     requests RetainedObjectInfos for persistent handles that
+ *     were not previously reported via AddObjectGroup.
+ *
+ * Thus, if an embedder wants to provide information about native
+ * objects for heap snapshots, he can do it in a GC prologue
+ * handler, and / or by assigning wrapper class ids in the following way:
+ *
+ *  1. Bind a callback to class id by calling DefineWrapperClass.
+ *  2. Call SetWrapperClassId on certain persistent handles.
+ *
+ * V8 takes ownership of RetainedObjectInfo instances passed to it and
+ * keeps them alive only during snapshot collection. Afterwards, they
+ * are freed by calling the Dispose class function.
+ */
+class V8EXPORT RetainedObjectInfo {  // NOLINT
+ public:
+  /** Called by V8 when it no longer needs an instance. */
+  virtual void Dispose() = 0;
+
+  /** Returns whether two instances are equivalent. */
+  virtual bool IsEquivalent(RetainedObjectInfo* other) = 0;
+
+  /**
+   * Returns hash value for the instance. Equivalent instances
+   * must have the same hash value.
+   */
+  virtual intptr_t GetHash() = 0;
+
+  /**
+   * Returns human-readable label. It must be a NUL-terminated UTF-8
+   * encoded string. V8 copies its contents during a call to GetLabel.
+   */
+  virtual const char* GetLabel() = 0;
+
+  /**
+   * Returns element count in case if a global handle retains
+   * a subgraph by holding one of its nodes.
+   */
+  virtual intptr_t GetElementCount() { return -1; }
+
+  /** Returns embedder's object size in bytes. */
+  virtual intptr_t GetSizeInBytes() { return -1; }
+
+ protected:
+  RetainedObjectInfo() {}
+  virtual ~RetainedObjectInfo() {}
+
+ private:
+  RetainedObjectInfo(const RetainedObjectInfo&);
+  RetainedObjectInfo& operator=(const RetainedObjectInfo&);
 };