libv8 6.2.414.42.0beta1-universal-darwin-15 → 8.4.255.0-universal-darwin-15

data/vendor/v8/include/v8-profiler.h

@@ -5,9 +5,12 @@
 #ifndef V8_V8_PROFILER_H_
 #define V8_V8_PROFILER_H_
 
+#include <limits.h>
+#include <memory>
 #include <unordered_set>
 #include <vector>
-#include "v8.h"  // NOLINT(build/include)
+
+#include "v8.h"  // NOLINT(build/include_directory)
 
 /**
  * Profiler support for the V8 JavaScript engine.
@@ -17,14 +20,18 @@ namespace v8 {
 class HeapGraphNode;
 struct HeapStatsUpdate;
 
-typedef uint32_t SnapshotObjectId;
-
+using NativeObject = void*;
+using SnapshotObjectId = uint32_t;
 
 struct CpuProfileDeoptFrame {
   int script_id;
   size_t position;
 };
 
+namespace internal {
+class CpuProfile;
+}  // namespace internal
+
 }  // namespace v8
 
 #ifdef V8_OS_WIN
@@ -47,89 +54,6 @@ template class V8_EXPORT std::vector;
 
 namespace v8 {
 
-/**
- * TracingCpuProfiler monitors tracing being enabled/disabled
- * and emits CpuProfile trace events once v8.cpu_profiler tracing category
- * is enabled. It has no overhead unless the category is enabled.
- */
-class V8_EXPORT TracingCpuProfiler {
- public:
-  static std::unique_ptr<TracingCpuProfiler> Create(Isolate*);
-  virtual ~TracingCpuProfiler() = default;
-
- protected:
-  TracingCpuProfiler() = default;
-};
-
-// TickSample captures the information collected for each sample.
-struct TickSample {
-  // Internal profiling (with --prof + tools/$OS-tick-processor) wants to
-  // include the runtime function we're calling. Externally exposed tick
-  // samples don't care.
-  enum RecordCEntryFrame { kIncludeCEntryFrame, kSkipCEntryFrame };
-
-  TickSample()
-      : state(OTHER),
-        pc(nullptr),
-        external_callback_entry(nullptr),
-        frames_count(0),
-        has_external_callback(false),
-        update_stats(true) {}
-
-  /**
-   * Initialize a tick sample from the isolate.
-   * \param isolate The isolate.
-   * \param state Execution state.
-   * \param record_c_entry_frame Include or skip the runtime function.
-   * \param update_stats Whether update the sample to the aggregated stats.
-   * \param use_simulator_reg_state When set to true and V8 is running under a
-   *                                simulator, the method will use the simulator
-   *                                register state rather than the one provided
-   *                                with |state| argument. Otherwise the method
-   *                                will use provided register |state| as is.
-   */
-  void Init(Isolate* isolate, const v8::RegisterState& state,
-            RecordCEntryFrame record_c_entry_frame, bool update_stats,
-            bool use_simulator_reg_state = true);
-  /**
-   * Get a call stack sample from the isolate.
-   * \param isolate The isolate.
-   * \param state Register state.
-   * \param record_c_entry_frame Include or skip the runtime function.
-   * \param frames Caller allocated buffer to store stack frames.
-   * \param frames_limit Maximum number of frames to capture. The buffer must
-   *                     be large enough to hold the number of frames.
-   * \param sample_info The sample info is filled up by the function
-   *                    provides number of actual captured stack frames and
-   *                    the current VM state.
-   * \param use_simulator_reg_state When set to true and V8 is running under a
-   *                                simulator, the method will use the simulator
-   *                                register state rather than the one provided
-   *                                with |state| argument. Otherwise the method
-   *                                will use provided register |state| as is.
-   * \note GetStackSample is thread and signal safe and should only be called
-   *                      when the JS thread is paused or interrupted.
-   *                      Otherwise the behavior is undefined.
-   */
-  static bool GetStackSample(Isolate* isolate, v8::RegisterState* state,
-                             RecordCEntryFrame record_c_entry_frame,
-                             void** frames, size_t frames_limit,
-                             v8::SampleInfo* sample_info,
-                             bool use_simulator_reg_state = true);
-  StateTag state;  // The state of the VM.
-  void* pc;        // Instruction pointer.
-  union {
-    void* tos;  // Top stack value (*sp).
-    void* external_callback_entry;
-  };
-  static const unsigned kMaxFramesCountLog2 = 8;
-  static const unsigned kMaxFramesCount = (1 << kMaxFramesCountLog2) - 1;
-  void* stack[kMaxFramesCount];                 // Call stack.
-  unsigned frames_count : kMaxFramesCountLog2;  // Number of captured frames.
-  bool has_external_callback : 1;
-  bool update_stats : 1;  // Whether the sample should update aggregated stats.
-};
-
 /**
  * CpuProfileNode represents a node in a call graph.
  */
@@ -143,6 +67,20 @@ class V8_EXPORT CpuProfileNode {
     unsigned int hit_count;
   };
 
+  // An annotation hinting at the source of a CpuProfileNode.
+  enum SourceType {
+    // User-supplied script with associated resource information.
+    kScript = 0,
+    // Native scripts and provided builtins.
+    kBuiltin = 1,
+    // Callbacks into native code.
+    kCallback = 2,
+    // VM-internal functions or state.
+    kInternal = 3,
+    // A node that failed to symbolize.
+    kUnresolved = 4,
+  };
+
   /** Returns function name (empty string for anonymous functions.) */
   Local<String> GetFunctionName() const;
 
@@ -166,6 +104,12 @@ class V8_EXPORT CpuProfileNode {
    */
   const char* GetScriptResourceNameStr() const;
 
+  /**
+   * Return true if the script from where the function originates is flagged as
+   * being shared cross-origin.
+   */
+  bool IsScriptSharedCrossOrigin() const;
+
   /**
    * Returns the number, 1-based, of the line where the function originates.
    * kNoLineNumberInfo if no line number information is available.
@@ -200,20 +144,23 @@ class V8_EXPORT CpuProfileNode {
     */
   unsigned GetHitCount() const;
 
-  /** Returns function entry UID. */
-  V8_DEPRECATE_SOON(
-      "Use GetScriptId, GetLineNumber, and GetColumnNumber instead.",
-      unsigned GetCallUid() const);
-
   /** Returns id of the node. The id is unique within the tree */
   unsigned GetNodeId() const;
 
+  /**
+   * Gets the type of the source which the node was captured from.
+   */
+  SourceType GetSourceType() const;
+
   /** Returns child nodes count of the node. */
   int GetChildrenCount() const;
 
   /** Retrieves a child node by index. */
   const CpuProfileNode* GetChild(int index) const;
 
+  /** Retrieves the ancestor node, or null if the root. */
+  const CpuProfileNode* GetParent() const;
+
   /** Retrieves deopt infos for the node. */
   const std::vector<CpuProfileDeoptInfo>& GetDeoptInfos() const;
 
@@ -273,6 +220,76 @@ class V8_EXPORT CpuProfile {
   void Delete();
 };
 
+enum CpuProfilingMode {
+  // In the resulting CpuProfile tree, intermediate nodes in a stack trace
+  // (from the root to a leaf) will have line numbers that point to the start
+  // line of the function, rather than the line of the callsite of the child.
+  kLeafNodeLineNumbers,
+  // In the resulting CpuProfile tree, nodes are separated based on the line
+  // number of their callsite in their parent.
+  kCallerLineNumbers,
+};
+
+// Determines how names are derived for functions sampled.
+enum CpuProfilingNamingMode {
+  // Use the immediate name of functions at compilation time.
+  kStandardNaming,
+  // Use more verbose naming for functions without names, inferred from scope
+  // where possible.
+  kDebugNaming,
+};
+
+enum CpuProfilingLoggingMode {
+  // Enables logging when a profile is active, and disables logging when all
+  // profiles are detached.
+  kLazyLogging,
+  // Enables logging for the lifetime of the CpuProfiler. Calls to
+  // StartRecording are faster, at the expense of runtime overhead.
+  kEagerLogging,
+};
+
+/**
+ * Optional profiling attributes.
+ */
+class V8_EXPORT CpuProfilingOptions {
+ public:
+  // Indicates that the sample buffer size should not be explicitly limited.
+  static const unsigned kNoSampleLimit = UINT_MAX;
+
+  /**
+   * \param mode Type of computation of stack frame line numbers.
+   * \param max_samples The maximum number of samples that should be recorded by
+   *                    the profiler. Samples obtained after this limit will be
+   *                    discarded.
+   * \param sampling_interval_us controls the profile-specific target
+   *                             sampling interval. The provided sampling
+   *                             interval will be snapped to the next lowest
+   *                             non-zero multiple of the profiler's sampling
+   *                             interval, set via SetSamplingInterval(). If
+   *                             zero, the sampling interval will be equal to
+   *                             the profiler's sampling interval.
+   */
+  CpuProfilingOptions(
+      CpuProfilingMode mode = kLeafNodeLineNumbers,
+      unsigned max_samples = kNoSampleLimit, int sampling_interval_us = 0,
+      MaybeLocal<Context> filter_context = MaybeLocal<Context>());
+
+  CpuProfilingMode mode() const { return mode_; }
+  unsigned max_samples() const { return max_samples_; }
+  int sampling_interval_us() const { return sampling_interval_us_; }
+
+ private:
+  friend class internal::CpuProfile;
+
+  bool has_filter_context() const { return !filter_context_.IsEmpty(); }
+  void* raw_filter_context() const;
+
+  CpuProfilingMode mode_;
+  unsigned max_samples_;
+  int sampling_interval_us_;
+  CopyablePersistentTraits<Context>::CopyablePersistent filter_context_;
+};
+
 /**
  * Interface for controlling CPU profiling. Instance of the
  * profiler can be created using v8::CpuProfiler::New method.
@@ -284,7 +301,16 @@ class V8_EXPORT CpuProfiler {
    * initialized. The profiler object must be disposed after use by calling
    * |Dispose| method.
    */
-  static CpuProfiler* New(Isolate* isolate);
+  static CpuProfiler* New(Isolate* isolate,
+                          CpuProfilingNamingMode = kDebugNaming,
+                          CpuProfilingLoggingMode = kLazyLogging);
+
+  /**
+   * Synchronously collect current stack sample in all profilers attached to
+   * the |isolate|. The call does not affect number of ticks recorded for
+   * the current top node.
+   */
+  static void CollectSample(Isolate* isolate);
 
   /**
    * Disposes the CPU profiler object.
@@ -299,15 +325,39 @@ class V8_EXPORT CpuProfiler {
   void SetSamplingInterval(int us);
 
   /**
-   * Starts collecting CPU profile. Title may be an empty string. It
-   * is allowed to have several profiles being collected at
-   * once. Attempts to start collecting several profiles with the same
-   * title are silently ignored. While collecting a profile, functions
-   * from all security contexts are included in it. The token-based
-   * filtering is only performed when querying for a profile.
+   * Sets whether or not the profiler should prioritize consistency of sample
+   * periodicity on Windows. Disabling this can greatly reduce CPU usage, but
+   * may result in greater variance in sample timings from the platform's
+   * scheduler. Defaults to enabled. This method must be called when there are
+   * no profiles being recorded.
+   */
+  void SetUsePreciseSampling(bool);
+
+  /**
+   * Starts collecting a CPU profile. Title may be an empty string. Several
+   * profiles may be collected at once. Attempts to start collecting several
+   * profiles with the same title are silently ignored.
+   */
+  void StartProfiling(Local<String> title, CpuProfilingOptions options);
+
+  /**
+   * Starts profiling with the same semantics as above, except with expanded
+   * parameters.
    *
    * |record_samples| parameter controls whether individual samples should
    * be recorded in addition to the aggregated tree.
+   *
+   * |max_samples| controls the maximum number of samples that should be
+   * recorded by the profiler. Samples obtained after this limit will be
+   * discarded.
+   */
+  void StartProfiling(
+      Local<String> title, CpuProfilingMode mode, bool record_samples = false,
+      unsigned max_samples = CpuProfilingOptions::kNoSampleLimit);
+  /**
+   * The same as StartProfiling above, but the CpuProfilingMode defaults to
+   * kLeafNodeLineNumbers mode, which was the previous default behavior of the
+   * profiler.
    */
   void StartProfiling(Local<String> title, bool record_samples = false);
 
@@ -318,16 +368,10 @@ class V8_EXPORT CpuProfiler {
   CpuProfile* StopProfiling(Local<String> title);
 
   /**
-   * Force collection of a sample. Must be called on the VM thread.
-   * Recording the forced sample does not contribute to the aggregated
-   * profile statistics.
+   * Generate more detailed source positions to code objects. This results in
+   * better results when mapping profiling samples to script source.
    */
-  void CollectSample();
-
-  /**
-   * Tells the profiler whether the embedder is idle.
-   */
-  void SetIdle(bool is_idle);
+  static void UseDetailedSourcePositionsForProfiling(Isolate* isolate);
 
  private:
   CpuProfiler();
@@ -336,7 +380,6 @@ class V8_EXPORT CpuProfiler {
   CpuProfiler& operator=(const CpuProfiler&);
 };
 
-
 /**
  * HeapSnapshotEdge represents a directed connection between heap
  * graph nodes: from retainers to retained nodes.
@@ -393,7 +436,8 @@ class V8_EXPORT HeapGraphNode {
                          // snapshot items together.
     kConsString = 10,    // Concatenated string. A pair of pointers to strings.
     kSlicedString = 11,  // Sliced string. A fragment of another string.
-    kSymbol = 12         // A Symbol (ES6).
+    kSymbol = 12,        // A Symbol (ES6).
+    kBigInt = 13         // BigInt.
   };
 
   /** Returns node type (see HeapGraphNode::Type). */
@@ -432,7 +476,7 @@ class V8_EXPORT OutputStream {  // NOLINT
     kContinue = 0,
     kAbort = 1
   };
-  virtual ~OutputStream() {}
+  virtual ~OutputStream() = default;
   /** Notify about the end of stream. */
   virtual void EndOfStream() = 0;
   /** Get preferred output chunk size. Called only once. */
@@ -526,7 +570,7 @@ class V8_EXPORT ActivityControl {  // NOLINT
     kContinue = 0,
     kAbort = 1
   };
-  virtual ~ActivityControl() {}
+  virtual ~ActivityControl() = default;
   /**
    * Notify about current progress. The activity can be stopped by
    * returning kAbort as the callback result.
@@ -592,6 +636,11 @@ class V8_EXPORT AllocationProfile {
      */
     int column_number;
 
+    /**
+     * Unique id of the node.
+     */
+    uint32_t node_id;
+
     /**
      * List of callees called from this node for which we have sampled
      * allocations. The lifetime of the children is scoped to the containing
@@ -605,19 +654,116 @@ class V8_EXPORT AllocationProfile {
     std::vector<Allocation> allocations;
   };
 
+  /**
+   * Represent a single sample recorded for an allocation.
+   */
+  struct Sample {
+    /**
+     * id of the node in the profile tree.
+     */
+    uint32_t node_id;
+
+    /**
+     * Size of the sampled allocation object.
+     */
+    size_t size;
+
+    /**
+     * The number of objects of such size that were sampled.
+     */
+    unsigned int count;
+
+    /**
+     * Unique time-ordered id of the allocation sample. Can be used to track
+     * what samples were added or removed between two snapshots.
+     */
+    uint64_t sample_id;
+  };
+
   /**
    * Returns the root node of the call-graph. The root node corresponds to an
    * empty JS call-stack. The lifetime of the returned Node* is scoped to the
    * containing AllocationProfile.
    */
   virtual Node* GetRootNode() = 0;
+  virtual const std::vector<Sample>& GetSamples() = 0;
 
-  virtual ~AllocationProfile() {}
+  virtual ~AllocationProfile() = default;
 
   static const int kNoLineNumberInfo = Message::kNoLineNumberInfo;
   static const int kNoColumnNumberInfo = Message::kNoColumnInfo;
 };
 
+/**
+ * An object graph consisting of embedder objects and V8 objects.
+ * Edges of the graph are strong references between the objects.
+ * The embedder can build this graph during heap snapshot generation
+ * to include the embedder objects in the heap snapshot.
+ * Usage:
+ * 1) Define derived class of EmbedderGraph::Node for embedder objects.
+ * 2) Set the build embedder graph callback on the heap profiler using
+ *    HeapProfiler::AddBuildEmbedderGraphCallback.
+ * 3) In the callback use graph->AddEdge(node1, node2) to add an edge from
+ *    node1 to node2.
+ * 4) To represent references from/to V8 object, construct V8 nodes using
+ *    graph->V8Node(value).
+ */
+class V8_EXPORT EmbedderGraph {
+ public:
+  class Node {
+   public:
+    Node() = default;
+    virtual ~Node() = default;
+    virtual const char* Name() = 0;
+    virtual size_t SizeInBytes() = 0;
+    /**
+     * The corresponding V8 wrapper node if not null.
+     * During heap snapshot generation the embedder node and the V8 wrapper
+     * node will be merged into one node to simplify retaining paths.
+     */
+    virtual Node* WrapperNode() { return nullptr; }
+    virtual bool IsRootNode() { return false; }
+    /** Must return true for non-V8 nodes. */
+    virtual bool IsEmbedderNode() { return true; }
+    /**
+     * Optional name prefix. It is used in Chrome for tagging detached nodes.
+     */
+    virtual const char* NamePrefix() { return nullptr; }
+
+    /**
+     * Returns the NativeObject that can be used for querying the
+     * |HeapSnapshot|.
+     */
+    virtual NativeObject GetNativeObject() { return nullptr; }
+
+    Node(const Node&) = delete;
+    Node& operator=(const Node&) = delete;
+  };
+
+  /**
+   * Returns a node corresponding to the given V8 value. Ownership is not
+   * transferred. The result pointer is valid while the graph is alive.
+   */
+  virtual Node* V8Node(const v8::Local<v8::Value>& value) = 0;
+
+  /**
+   * Adds the given node to the graph and takes ownership of the node.
+   * Returns a raw pointer to the node that is valid while the graph is alive.
+   */
+  virtual Node* AddNode(std::unique_ptr<Node> node) = 0;
+
+  /**
+   * Adds an edge that represents a strong reference from the given
+   * node |from| to the given node |to|. The nodes must be added to the graph
+   * before calling this function.
+   *
+   * If name is nullptr, the edge will have auto-increment indexes, otherwise
+   * it will be named accordingly.
+   */
+  virtual void AddEdge(Node* from, Node* to, const char* name = nullptr) = 0;
+
+  virtual ~EmbedderGraph() = default;
+};
 
 /**
  * Interface for controlling heap profiling. Instance of the
@@ -630,32 +776,15 @@ class V8_EXPORT HeapProfiler {
     kSamplingForceGC = 1 << 0,
   };
 
-  typedef std::unordered_set<const v8::PersistentBase<v8::Value>*>
-      RetainerChildren;
-  typedef std::vector<std::pair<v8::RetainedObjectInfo*, RetainerChildren>>
-      RetainerGroups;
-  typedef std::vector<std::pair<const v8::PersistentBase<v8::Value>*,
-                                const v8::PersistentBase<v8::Value>*>>
-      RetainerEdges;
-
-  struct RetainerInfos {
-    RetainerGroups groups;
-    RetainerEdges edges;
-  };
-
   /**
-   * Callback function invoked to retrieve all RetainerInfos from the embedder.
+   * Callback function invoked during heap snapshot generation to retrieve
+   * the embedder object graph. The callback should use graph->AddEdge(..) to
+   * add references between the objects.
+   * The callback must not trigger garbage collection in V8.
    */
-  typedef RetainerInfos (*GetRetainerInfosCallback)(v8::Isolate* isolate);
-
-  /**
-   * 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,
-                                                     Local<Value> wrapper);
+  typedef void (*BuildEmbedderGraphCallback)(v8::Isolate* isolate,
+                                             v8::EmbedderGraph* graph,
+                                             void* data);
 
   /** Returns the number of snapshots taken. */
   int GetSnapshotCount();
@@ -669,6 +798,12 @@ class V8_EXPORT HeapProfiler {
    */
   SnapshotObjectId GetObjectId(Local<Value> value);
 
+  /**
+   * Returns SnapshotObjectId for a native object referenced by |value| if it
+   * has been seen by the heap profiler, kUnknownObjectId otherwise.
+   */
+  SnapshotObjectId GetObjectId(NativeObject value);
+
   /**
    * Returns heap object with given SnapshotObjectId if the object is alive,
    * otherwise empty handle is returned.
@@ -701,15 +836,16 @@ class V8_EXPORT HeapProfiler {
     virtual const char* GetName(Local<Object> object) = 0;
 
    protected:
-    virtual ~ObjectNameResolver() {}
+    virtual ~ObjectNameResolver() = default;
   };
 
   /**
    * Takes a heap snapshot and returns it.
    */
   const HeapSnapshot* TakeHeapSnapshot(
-      ActivityControl* control = NULL,
-      ObjectNameResolver* global_object_name_resolver = NULL);
+      ActivityControl* control = nullptr,
+      ObjectNameResolver* global_object_name_resolver = nullptr,
+      bool treat_global_objects_as_roots = true);
 
   /**
    * Starts tracking of heap objects population statistics. After calling
@@ -736,7 +872,7 @@ class V8_EXPORT HeapProfiler {
    * method.
    */
   SnapshotObjectId GetHeapStats(OutputStream* stream,
-                                int64_t* timestamp_us = NULL);
+                                int64_t* timestamp_us = nullptr);
 
   /**
    * Stops tracking of heap objects population statistics, cleans up all
@@ -795,12 +931,10 @@ class V8_EXPORT HeapProfiler {
    */
   void DeleteAllHeapSnapshots();
 
-  /** Binds a callback to embedder's class ID. */
-  void SetWrapperClassInfoProvider(
-      uint16_t class_id,
-      WrapperInfoCallback callback);
-
-  void SetGetRetainerInfosCallback(GetRetainerInfosCallback callback);
+  void AddBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
+                                     void* data);
+  void RemoveBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
+                                        void* data);
 
   /**
    * Default value of persistent handle class ID. Must not be used to
@@ -817,92 +951,108 @@ class V8_EXPORT HeapProfiler {
 };
 
 /**
- * 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, it 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 SetWrapperClassInfoProvider.
- *  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.
+ * A struct for exporting HeapStats data from V8, using "push" model.
+ * See HeapProfiler::GetHeapStats.
  */
-class V8_EXPORT RetainedObjectInfo {  // NOLINT
- public:
-  /** Called by V8 when it no longer needs an instance. */
-  virtual void Dispose() = 0;
+struct HeapStatsUpdate {
+  HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size)
+    : index(index), count(count), size(size) { }
+  uint32_t index;  // Index of the time interval that was changed.
+  uint32_t count;  // New value of count field for the interval with this index.
+  uint32_t size;  // New value of size field for the interval with this index.
+};
 
-  /** Returns whether two instances are equivalent. */
-  virtual bool IsEquivalent(RetainedObjectInfo* other) = 0;
+#define CODE_EVENTS_LIST(V) \
+  V(Builtin)                \
+  V(Callback)               \
+  V(Eval)                   \
+  V(Function)               \
+  V(InterpretedFunction)    \
+  V(Handler)                \
+  V(BytecodeHandler)        \
+  V(LazyCompile)            \
+  V(RegExp)                 \
+  V(Script)                 \
+  V(Stub)                   \
+  V(Relocation)
 
+/**
+ * Note that this enum may be extended in the future. Please include a default
+ * case if this enum is used in a switch statement.
+ */
+enum CodeEventType {
+  kUnknownType = 0
+#define V(Name) , k##Name##Type
+  CODE_EVENTS_LIST(V)
+#undef V
+};
+
+/**
+ * Representation of a code creation event
+ */
+class V8_EXPORT CodeEvent {
+ public:
+  uintptr_t GetCodeStartAddress();
+  size_t GetCodeSize();
+  Local<String> GetFunctionName();
+  Local<String> GetScriptName();
+  int GetScriptLine();
+  int GetScriptColumn();
   /**
-   * Returns hash value for the instance. Equivalent instances
-   * must have the same hash value.
+   * NOTE (mmarchini): We can't allocate objects in the heap when we collect
+   * existing code, and both the code type and the comment are not stored in the
+   * heap, so we return those as const char*.
    */
-  virtual intptr_t GetHash() = 0;
+  CodeEventType GetCodeType();
+  const char* GetComment();
+
+  static const char* GetCodeEventTypeName(CodeEventType code_event_type);
 
+  uintptr_t GetPreviousCodeStartAddress();
+};
+
+/**
+ * Interface to listen to code creation and code relocation events.
+ */
+class V8_EXPORT CodeEventHandler {
+ public:
   /**
-   * Returns human-readable label. It must be a null-terminated UTF-8
-   * encoded string. V8 copies its contents during a call to GetLabel.
+   * Creates a new listener for the |isolate|. The isolate must be initialized.
+   * The listener object must be disposed after use by calling |Dispose| method.
+   * Multiple listeners can be created for the same isolate.
    */
-  virtual const char* GetLabel() = 0;
+  explicit CodeEventHandler(Isolate* isolate);
+  virtual ~CodeEventHandler();
 
   /**
-   * Returns human-readable group label. It must be a null-terminated UTF-8
-   * encoded string. V8 copies its contents during a call to GetGroupLabel.
-   * Heap snapshot generator will collect all the group names, create
-   * top level entries with these names and attach the objects to the
-   * corresponding top level group objects. There is a default
-   * implementation which is required because embedders don't have their
-   * own implementation yet.
+   * Handle is called every time a code object is created or moved. Information
+   * about each code event will be available through the `code_event`
+   * parameter.
+   *
+   * When the CodeEventType is kRelocationType, the code for this CodeEvent has
+   * moved from `GetPreviousCodeStartAddress()` to `GetCodeStartAddress()`.
    */
-  virtual const char* GetGroupLabel() { return GetLabel(); }
+  virtual void Handle(CodeEvent* code_event) = 0;
 
   /**
-   * Returns element count in case if a global handle retains
-   * a subgraph by holding one of its nodes.
+   * Call `Enable()` to starts listening to code creation and code relocation
+   * events. These events will be handled by `Handle()`.
    */
-  virtual intptr_t GetElementCount() { return -1; }
-
-  /** Returns embedder's object size in bytes. */
-  virtual intptr_t GetSizeInBytes() { return -1; }
+  void Enable();
 
- protected:
-  RetainedObjectInfo() {}
-  virtual ~RetainedObjectInfo() {}
+  /**
+   * Call `Disable()` to stop listening to code creation and code relocation
+   * events.
+   */
+  void Disable();
 
  private:
-  RetainedObjectInfo(const RetainedObjectInfo&);
-  RetainedObjectInfo& operator=(const RetainedObjectInfo&);
+  CodeEventHandler();
+  CodeEventHandler(const CodeEventHandler&);
+  CodeEventHandler& operator=(const CodeEventHandler&);
+  void* internal_listener_;
 };
 
-
-/**
- * A struct for exporting HeapStats data from V8, using "push" model.
- * See HeapProfiler::GetHeapStats.
- */
-struct HeapStatsUpdate {
-  HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size)
-    : index(index), count(count), size(size) { }
-  uint32_t index;  // Index of the time interval that was changed.
-  uint32_t count;  // New value of count field for the interval with this index.
-  uint32_t size;  // New value of size field for the interval with this index.
-};
-
-
 }  // namespace v8