Add an interface for an embedder to provide information about native

include/v8.h

 // Copyright 2007-2009 the V8 project authors. All rights reserved.
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 //       notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
 //       copyright notice, this list of conditions and the following
 //       disclaimer in the documentation and/or other materials provided
@@ skipping 378 matching lines @@
   /**
    *Checks if the handle holds the only reference to an object.
    */
   inline bool IsNearDeath() const;
 
   /**
    * Returns true if the handle's reference is weak.
    */
   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
  * allocated within that handle scope until either the handle scope is
  * deleted or another handle scope is created.  If there is already a
  * handle scope and a new one is created, all allocations will take
  * place in the new handle scope until it is deleted.  After that,
  * new handles will again be allocated in the original handle scope.
  *
  * After the handle scope of a local handle has been deleted the
@@ skipping 2112 matching lines @@
   size_t total_heap_size_;
   size_t total_heap_size_executable_;
   size_t used_heap_size_;
   size_t heap_size_limit_;
 
   friend class V8;
 };
 
 
 /**
+ * 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 {
  public:
   /** Set the callback to invoke in case of fatal errors. */
   static void SetFatalErrorHandler(FatalErrorCallback that);
 
   /**
    * Ignore out-of-memory exceptions.
    *
@@ skipping 149 matching lines @@
   static void RemoveMemoryAllocationCallback(MemoryAllocationCallback callback);
 
   /**
    * Allows the host application to group objects together. If one
    * object in the group is alive, all objects in the group are alive.
    * After each garbage collection, object groups are removed. It is
    * intended to be used in the before-garbage-collection callback
    * 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
    * initialize from scratch.  This function is called implicitly if
    * you use the API without calling it first.
    */
   static bool Initialize();
 
   /**
    * Adjusts the amount of registered external memory.  Used to give
@@ skipping 188 matching lines @@
   V8();
 
   static internal::Object** GlobalizeReference(internal::Object** handle);
   static void DisposeGlobal(internal::Object** global_handle);
   static void MakeWeak(internal::Object** global_handle,
                        void* data,
                        WeakReferenceCallback);
   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;
   template <class T> friend class Persistent;
   friend class Context;
 };
 
 
 /**
  * An external exception handler.
@@ skipping 628 matching lines @@
   V8::MakeWeak(reinterpret_cast<internal::Object**>(**this),
                parameters,
                callback);
 }
 
 template <class T>
 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,
                      bool is_construct_call)
     : implicit_args_(implicit_args),
       values_(values),
       length_(length),
       is_construct_call_(is_construct_call) { }
 
 
@@ skipping 264 matching lines @@
 
 
 }  // namespace v8
 
 
 #undef V8EXPORT
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_