Add an interface for an embedder to provide information about native

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index 83a5744278afe03f7a7869379f17217e74a80ea4..c036845b6718c6e52046bc29295d40e0b996d671 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -396,12 +396,24 @@ template <class T> class Persistent : public Handle<T> {
    */
   inline bool IsWeak() const;
 
+  /**
+   * Assigns a class ID to the handle. See RetainedObjectInfo

[Vitaly Repeshko, 2011/03/09 14:15:49]

"a class" -> "a wrapper class"

[mnaganov (inactive), 2011/03/09 15:26:32]

Done.

+   * interface description for details.
+   */
+  inline void SetWrapperClassId(uint16_t class_id);
+
  private:
   friend class ImplementationUtilities;
   friend class ObjectTemplate;
 };
 
 
+/**
+ * Default value of persistent handle class ID.
+ */
+static const uint16_t kPersistentHandleNoClassId = 0;
+
+
  /**
  * A stack-allocated class that governs a number of local handles.
  * After a handle scope has been created, all local handles will be
@@ -2534,6 +2546,66 @@ class V8EXPORT HeapStatistics {
 
 
 /**
+ * Interface for providing information about embedder's objects

[Vitaly Repeshko, 2011/03/09 14:15:49]

Is there a good reason to keep this interface here and not in v8-profile.h? Also
please mention in the very first sentence here that the interface is used by the
heap profiler.

[mnaganov (inactive), 2011/03/09 15:26:32]

After I have moved to v8-profiler.h near HeapProfiler this is no more needed, I
think.

+ * 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.
+ *
+ * Returned RetainedObjectInfo instances are kept alive only during

[Vitaly Repeshko, 2011/03/09 14:15:49]

Let's change the first sentence to "V8 takes ownership of RetainedObjectInfo
instances passed to it and keeps them alive only during snapshot collection".

[mnaganov (inactive), 2011/03/09 15:26:32]

Done.

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

[Vitaly Repeshko, 2011/03/09 14:15:49]

Please document the expected encoding (and whether it should be NUL-terminated)
and the ownership of the returned pointer.

[mnaganov (inactive), 2011/03/09 15:26:32]

Done.

+  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&);
+};
+
+
+/**
  * Container class for static utility functions.
  */
 class V8EXPORT V8 {
@@ -2703,7 +2775,9 @@ class V8EXPORT V8 {
    * function, for instance to simulate DOM tree connections among JS
    * wrapper objects.
    */
-  static void AddObjectGroup(Persistent<Value>* objects, size_t length);
+  static void AddObjectGroup(Persistent<Value>* objects,
+                             size_t length,
+                             RetainedObjectInfo* info = NULL);
 
   /**
    * Initializes from snapshot if possible. Otherwise, attempts to
@@ -2912,6 +2986,8 @@ class V8EXPORT V8 {
   static void ClearWeak(internal::Object** global_handle);
   static bool IsGlobalNearDeath(internal::Object** global_handle);
   static bool IsGlobalWeak(internal::Object** global_handle);
+  static void SetWrapperClassId(internal::Object** global_handle,
+                                uint16_t class_id);
 
   template <class T> friend class Handle;
   template <class T> friend class Local;
@@ -3560,6 +3636,10 @@ void Persistent<T>::ClearWeak() {
   V8::ClearWeak(reinterpret_cast<internal::Object**>(**this));
 }
 
+template <class T>
+void Persistent<T>::SetWrapperClassId(uint16_t class_id) {
+  V8::SetWrapperClassId(reinterpret_cast<internal::Object**>(**this), class_id);
+}
 
 Arguments::Arguments(internal::Object** implicit_args,
                      internal::Object** values, int length,