V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
v8-profiler.h
1 // Copyright 2010 the V8 project authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef V8_V8_PROFILER_H_
6 #define V8_V8_PROFILER_H_
7 
8 #include <unordered_set>
9 #include <vector>
10 #include "v8.h" // NOLINT(build/include)
11 
15 namespace v8 {
16 
17 class HeapGraphNode;
18 struct HeapStatsUpdate;
19 
20 typedef uint32_t SnapshotObjectId;
21 
22 
24  int script_id;
25  size_t position;
26 };
27 
28 } // namespace v8
29 
30 #ifdef V8_OS_WIN
31 template class V8_EXPORT std::vector<v8::CpuProfileDeoptFrame>;
32 #endif
33 
34 namespace v8 {
35 
36 struct V8_EXPORT CpuProfileDeoptInfo {
38  const char* deopt_reason;
39  std::vector<CpuProfileDeoptFrame> stack;
40 };
41 
42 } // namespace v8
43 
44 #ifdef V8_OS_WIN
45 template class V8_EXPORT std::vector<v8::CpuProfileDeoptInfo>;
46 #endif
47 
48 namespace v8 {
49 
50 // TickSample captures the information collected for each sample.
51 struct TickSample {
52  // Internal profiling (with --prof + tools/$OS-tick-processor) wants to
53  // include the runtime function we're calling. Externally exposed tick
54  // samples don't care.
55  enum RecordCEntryFrame { kIncludeCEntryFrame, kSkipCEntryFrame };
56 
57  TickSample()
58  : state(OTHER),
59  pc(nullptr),
60  external_callback_entry(nullptr),
61  frames_count(0),
62  has_external_callback(false),
63  update_stats(true) {}
64 
77  void Init(Isolate* isolate, const v8::RegisterState& state,
78  RecordCEntryFrame record_c_entry_frame, bool update_stats,
79  bool use_simulator_reg_state = true);
100  static bool GetStackSample(Isolate* isolate, v8::RegisterState* state,
101  RecordCEntryFrame record_c_entry_frame,
102  void** frames, size_t frames_limit,
103  v8::SampleInfo* sample_info,
104  bool use_simulator_reg_state = true);
105  StateTag state; // The state of the VM.
106  void* pc; // Instruction pointer.
107  union {
108  void* tos; // Top stack value (*sp).
109  void* external_callback_entry;
110  };
111  static const unsigned kMaxFramesCountLog2 = 8;
112  static const unsigned kMaxFramesCount = (1 << kMaxFramesCountLog2) - 1;
113  void* stack[kMaxFramesCount]; // Call stack.
114  unsigned frames_count : kMaxFramesCountLog2; // Number of captured frames.
115  bool has_external_callback : 1;
116  bool update_stats : 1; // Whether the sample should update aggregated stats.
117 };
118 
122 class V8_EXPORT CpuProfileNode {
123  public:
124  struct LineTick {
126  int line;
127 
129  unsigned int hit_count;
130  };
131 
133  Local<String> GetFunctionName() const;
134 
140  const char* GetFunctionNameStr() const;
141 
143  int GetScriptId() const;
144 
146  Local<String> GetScriptResourceName() const;
147 
153  const char* GetScriptResourceNameStr() const;
154 
159  int GetLineNumber() const;
160 
165  int GetColumnNumber() const;
166 
170  unsigned int GetHitLineCount() const;
171 
177  bool GetLineTicks(LineTick* entries, unsigned int length) const;
178 
182  const char* GetBailoutReason() const;
183 
187  unsigned GetHitCount() const;
188 
190  V8_DEPRECATE_SOON(
191  "Use GetScriptId, GetLineNumber, and GetColumnNumber instead.",
192  unsigned GetCallUid() const);
193 
195  unsigned GetNodeId() const;
196 
198  int GetChildrenCount() const;
199 
201  const CpuProfileNode* GetChild(int index) const;
202 
204  const std::vector<CpuProfileDeoptInfo>& GetDeoptInfos() const;
205 
206  static const int kNoLineNumberInfo = Message::kNoLineNumberInfo;
207  static const int kNoColumnNumberInfo = Message::kNoColumnInfo;
208 };
209 
210 
215 class V8_EXPORT CpuProfile {
216  public:
218  Local<String> GetTitle() const;
219 
221  const CpuProfileNode* GetTopDownRoot() const;
222 
227  int GetSamplesCount() const;
228 
233  const CpuProfileNode* GetSample(int index) const;
234 
240  int64_t GetSampleTimestamp(int index) const;
241 
246  int64_t GetStartTime() const;
247 
253  int64_t GetEndTime() const;
254 
259  void Delete();
260 };
261 
262 enum CpuProfilingMode {
263  // In the resulting CpuProfile tree, intermediate nodes in a stack trace
264  // (from the root to a leaf) will have line numbers that point to the start
265  // line of the function, rather than the line of the callsite of the child.
266  kLeafNodeLineNumbers,
267  // In the resulting CpuProfile tree, nodes are separated based on the line
268  // number of their callsite in their parent.
269  kCallerLineNumbers,
270 };
271 
276 class V8_EXPORT CpuProfiler {
277  public:
283  static CpuProfiler* New(Isolate* isolate);
284 
290  static void CollectSample(Isolate* isolate);
291 
295  void Dispose();
296 
302  void SetSamplingInterval(int us);
303 
315  void StartProfiling(Local<String> title, CpuProfilingMode mode,
316  bool record_samples = false);
322  void StartProfiling(Local<String> title, bool record_samples = false);
323 
328  CpuProfile* StopProfiling(Local<String> title);
329 
335  V8_DEPRECATED("Use static CollectSample(Isolate*) instead.",
336  void CollectSample());
337 
341  V8_DEPRECATED("Use Isolate::SetIdle(bool) instead.",
342  void SetIdle(bool is_idle));
343 
348  static void UseDetailedSourcePositionsForProfiling(Isolate* isolate);
349 
350  private:
351  CpuProfiler();
352  ~CpuProfiler();
353  CpuProfiler(const CpuProfiler&);
354  CpuProfiler& operator=(const CpuProfiler&);
355 };
356 
357 
362 class V8_EXPORT HeapGraphEdge {
363  public:
364  enum Type {
365  kContextVariable = 0, // A variable from a function context.
366  kElement = 1, // An element of an array.
367  kProperty = 2, // A named object property.
368  kInternal = 3, // A link that can't be accessed from JS,
369  // thus, its name isn't a real property name
370  // (e.g. parts of a ConsString).
371  kHidden = 4, // A link that is needed for proper sizes
372  // calculation, but may be hidden from user.
373  kShortcut = 5, // A link that must not be followed during
374  // sizes calculation.
375  kWeak = 6 // A weak reference (ignored by the GC).
376  };
377 
379  Type GetType() const;
380 
385  Local<Value> GetName() const;
386 
388  const HeapGraphNode* GetFromNode() const;
389 
391  const HeapGraphNode* GetToNode() const;
392 };
393 
394 
398 class V8_EXPORT HeapGraphNode {
399  public:
400  enum Type {
401  kHidden = 0, // Hidden node, may be filtered when shown to user.
402  kArray = 1, // An array of elements.
403  kString = 2, // A string.
404  kObject = 3, // A JS object (except for arrays and strings).
405  kCode = 4, // Compiled code.
406  kClosure = 5, // Function closure.
407  kRegExp = 6, // RegExp.
408  kHeapNumber = 7, // Number stored in the heap.
409  kNative = 8, // Native object (not from V8 heap).
410  kSynthetic = 9, // Synthetic object, usually used for grouping
411  // snapshot items together.
412  kConsString = 10, // Concatenated string. A pair of pointers to strings.
413  kSlicedString = 11, // Sliced string. A fragment of another string.
414  kSymbol = 12, // A Symbol (ES6).
415  kBigInt = 13 // BigInt.
416  };
417 
419  Type GetType() const;
420 
426  Local<String> GetName() const;
427 
432  SnapshotObjectId GetId() const;
433 
435  size_t GetShallowSize() const;
436 
438  int GetChildrenCount() const;
439 
441  const HeapGraphEdge* GetChild(int index) const;
442 };
443 
444 
448 class V8_EXPORT OutputStream { // NOLINT
449  public:
450  enum WriteResult {
451  kContinue = 0,
452  kAbort = 1
453  };
454  virtual ~OutputStream() = default;
456  virtual void EndOfStream() = 0;
458  virtual int GetChunkSize() { return 1024; }
464  virtual WriteResult WriteAsciiChunk(char* data, int size) = 0;
470  virtual WriteResult WriteHeapStatsChunk(HeapStatsUpdate* data, int count) {
471  return kAbort;
472  }
473 };
474 
475 
479 class V8_EXPORT HeapSnapshot {
480  public:
481  enum SerializationFormat {
482  kJSON = 0 // See format description near 'Serialize' method.
483  };
484 
486  const HeapGraphNode* GetRoot() const;
487 
489  const HeapGraphNode* GetNodeById(SnapshotObjectId id) const;
490 
492  int GetNodesCount() const;
493 
495  const HeapGraphNode* GetNode(int index) const;
496 
498  SnapshotObjectId GetMaxSnapshotJSObjectId() const;
499 
505  void Delete();
506 
533  void Serialize(OutputStream* stream,
534  SerializationFormat format = kJSON) const;
535 };
536 
537 
542 class V8_EXPORT ActivityControl { // NOLINT
543  public:
544  enum ControlOption {
545  kContinue = 0,
546  kAbort = 1
547  };
548  virtual ~ActivityControl() = default;
553  virtual ControlOption ReportProgressValue(int done, int total) = 0;
554 };
555 
556 
561 class V8_EXPORT AllocationProfile {
562  public:
563  struct Allocation {
567  size_t size;
568 
572  unsigned int count;
573  };
574 
578  struct Node {
584 
590 
596 
601 
607 
613 
618 
624  std::vector<Node*> children;
625 
629  std::vector<Allocation> allocations;
630  };
631 
635  struct Sample {
640 
644  size_t size;
645 
649  unsigned int count;
650 
655  uint64_t sample_id;
656  };
657 
663  virtual Node* GetRootNode() = 0;
664  virtual const std::vector<Sample>& GetSamples() = 0;
665 
666  virtual ~AllocationProfile() = default;
667 
668  static const int kNoLineNumberInfo = Message::kNoLineNumberInfo;
669  static const int kNoColumnNumberInfo = Message::kNoColumnInfo;
670 };
671 
686 class V8_EXPORT EmbedderGraph {
687  public:
688  class Node {
689  public:
690  Node() = default;
691  virtual ~Node() = default;
692  virtual const char* Name() = 0;
693  virtual size_t SizeInBytes() = 0;
699  virtual Node* WrapperNode() { return nullptr; }
700  virtual bool IsRootNode() { return false; }
702  virtual bool IsEmbedderNode() { return true; }
706  virtual const char* NamePrefix() { return nullptr; }
707 
708  private:
709  Node(const Node&) = delete;
710  Node& operator=(const Node&) = delete;
711  };
712 
717  virtual Node* V8Node(const v8::Local<v8::Value>& value) = 0;
718 
723  virtual Node* AddNode(std::unique_ptr<Node> node) = 0;
724 
733  virtual void AddEdge(Node* from, Node* to, const char* name = nullptr) = 0;
734 
735  virtual ~EmbedderGraph() = default;
736 };
737 
742 class V8_EXPORT HeapProfiler {
743  public:
744  enum SamplingFlags {
745  kSamplingNoFlags = 0,
746  kSamplingForceGC = 1 << 0,
747  };
748 
749  typedef std::unordered_set<const v8::PersistentBase<v8::Value>*>
750  RetainerChildren;
751  typedef std::vector<std::pair<v8::RetainedObjectInfo*, RetainerChildren>>
752  RetainerGroups;
753  typedef std::vector<std::pair<const v8::PersistentBase<v8::Value>*,
755  RetainerEdges;
756 
757  struct RetainerInfos {
758  RetainerGroups groups;
759  RetainerEdges edges;
760  };
761 
765  typedef RetainerInfos (*GetRetainerInfosCallback)(v8::Isolate* isolate);
766 
773  typedef RetainedObjectInfo* (*WrapperInfoCallback)(uint16_t class_id,
774  Local<Value> wrapper);
775 
782  typedef void (*BuildEmbedderGraphCallback)(v8::Isolate* isolate,
783  v8::EmbedderGraph* graph,
784  void* data);
785 
787  typedef void (*LegacyBuildEmbedderGraphCallback)(v8::Isolate* isolate,
788  v8::EmbedderGraph* graph);
789 
791  int GetSnapshotCount();
792 
794  const HeapSnapshot* GetHeapSnapshot(int index);
795 
800  SnapshotObjectId GetObjectId(Local<Value> value);
801 
806  Local<Value> FindObjectById(SnapshotObjectId id);
807 
813  void ClearObjectIds();
814 
820  static const SnapshotObjectId kUnknownObjectId = 0;
821 
826  public:
831  virtual const char* GetName(Local<Object> object) = 0;
832 
833  protected:
834  virtual ~ObjectNameResolver() = default;
835  };
836 
840  const HeapSnapshot* TakeHeapSnapshot(
841  ActivityControl* control = nullptr,
842  ObjectNameResolver* global_object_name_resolver = nullptr);
843 
853  void StartTrackingHeapObjects(bool track_allocations = false);
854 
868  SnapshotObjectId GetHeapStats(OutputStream* stream,
869  int64_t* timestamp_us = nullptr);
870 
876  void StopTrackingHeapObjects();
877 
905  bool StartSamplingHeapProfiler(uint64_t sample_interval = 512 * 1024,
906  int stack_depth = 16,
907  SamplingFlags flags = kSamplingNoFlags);
908 
912  void StopSamplingHeapProfiler();
913 
920  AllocationProfile* GetAllocationProfile();
921 
926  void DeleteAllHeapSnapshots();
927 
929  V8_DEPRECATED(
930  "Use AddBuildEmbedderGraphCallback to provide info about embedder nodes",
931  void SetWrapperClassInfoProvider(uint16_t class_id,
932  WrapperInfoCallback callback));
933 
934  V8_DEPRECATED(
935  "Use AddBuildEmbedderGraphCallback to provide info about embedder nodes",
936  void SetGetRetainerInfosCallback(GetRetainerInfosCallback callback));
937 
938  V8_DEPRECATED(
939  "Use AddBuildEmbedderGraphCallback to provide info about embedder nodes",
940  void SetBuildEmbedderGraphCallback(
941  LegacyBuildEmbedderGraphCallback callback));
942  void AddBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
943  void* data);
944  void RemoveBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
945  void* data);
946 
952  static const uint16_t kPersistentHandleNoClassId = 0;
953 
954  private:
955  HeapProfiler();
956  ~HeapProfiler();
957  HeapProfiler(const HeapProfiler&);
958  HeapProfiler& operator=(const HeapProfiler&);
959 };
960 
985 class V8_EXPORT RetainedObjectInfo { // NOLINT
986  public:
988  virtual void Dispose() = 0;
989 
991  virtual bool IsEquivalent(RetainedObjectInfo* other) = 0;
992 
997  virtual intptr_t GetHash() = 0;
998 
1003  virtual const char* GetLabel() = 0;
1004 
1014  virtual const char* GetGroupLabel() { return GetLabel(); }
1015 
1020  virtual intptr_t GetElementCount() { return -1; }
1021 
1023  virtual intptr_t GetSizeInBytes() { return -1; }
1024 
1025  protected:
1026  RetainedObjectInfo() = default;
1027  virtual ~RetainedObjectInfo() = default;
1028 
1029  private:
1031  RetainedObjectInfo& operator=(const RetainedObjectInfo&);
1032 };
1033 
1034 
1040  HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size)
1041  : index(index), count(count), size(size) { }
1042  uint32_t index; // Index of the time interval that was changed.
1043  uint32_t count; // New value of count field for the interval with this index.
1044  uint32_t size; // New value of size field for the interval with this index.
1045 };
1046 
1047 #define CODE_EVENTS_LIST(V) \
1048  V(Builtin) \
1049  V(Callback) \
1050  V(Eval) \
1051  V(Function) \
1052  V(InterpretedFunction) \
1053  V(Handler) \
1054  V(BytecodeHandler) \
1055  V(LazyCompile) \
1056  V(RegExp) \
1057  V(Script) \
1058  V(Stub)
1059 
1065  kUnknownType = 0
1066 #define V(Name) , k##Name##Type
1067  CODE_EVENTS_LIST(V)
1068 #undef V
1069 };
1070 
1074 class V8_EXPORT CodeEvent {
1075  public:
1076  uintptr_t GetCodeStartAddress();
1077  size_t GetCodeSize();
1078  Local<String> GetFunctionName();
1079  Local<String> GetScriptName();
1080  int GetScriptLine();
1081  int GetScriptColumn();
1087  CodeEventType GetCodeType();
1088  const char* GetComment();
1089 
1090  static const char* GetCodeEventTypeName(CodeEventType code_event_type);
1091 };
1092 
1096 class V8_EXPORT CodeEventHandler {
1097  public:
1103  explicit CodeEventHandler(Isolate* isolate);
1104  virtual ~CodeEventHandler();
1105 
1106  virtual void Handle(CodeEvent* code_event) = 0;
1107 
1108  void Enable();
1109  void Disable();
1110 
1111  private:
1112  CodeEventHandler();
1114  CodeEventHandler& operator=(const CodeEventHandler&);
1115  void* internal_listener_;
1116 };
1117 
1118 } // namespace v8
1119 
1120 
1121 #endif // V8_V8_PROFILER_H_
virtual WriteResult WriteHeapStatsChunk(HeapStatsUpdate *data, int count)
Definition: v8-profiler.h:470
const char * deopt_reason
Definition: v8-profiler.h:38
virtual Node * WrapperNode()
Definition: v8-profiler.h:699
virtual intptr_t GetElementCount()
Definition: v8-profiler.h:1020
Definition: v8.h:2497
virtual bool IsEmbedderNode()
Definition: v8-profiler.h:702
Definition: v8.h:85
Local< String > script_name
Definition: v8-profiler.h:589
virtual int GetChunkSize()
Definition: v8-profiler.h:458
std::vector< Node * > children
Definition: v8-profiler.h:624
virtual intptr_t GetSizeInBytes()
Definition: v8-profiler.h:1023
Definition: libplatform.h:13
CodeEventType
Definition: v8-profiler.h:1064
virtual const char * GetGroupLabel()
Definition: v8-profiler.h:1014
virtual const char * NamePrefix()
Definition: v8-profiler.h:706
std::vector< Allocation > allocations
Definition: v8-profiler.h:629