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 12 /** 13 * Profiler support for the V8 JavaScript engine. 14 */ 15 namespace v8 { 16 17 class HeapGraphNode; 18 struct HeapStatsUpdate; 19 20 typedef uint32_t SnapshotObjectId; 21 22 23 struct CpuProfileDeoptFrame { 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 { 37 /** A pointer to a static string owned by v8. */ 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 /** 51 * TracingCpuProfiler monitors tracing being enabled/disabled 52 * and emits CpuProfile trace events once v8.cpu_profiler tracing category 53 * is enabled. It has no overhead unless the category is enabled. 54 */ 55 class V8_EXPORT TracingCpuProfiler { 56 public: 57 static std::unique_ptr<TracingCpuProfiler> Create(Isolate*); 58 virtual ~TracingCpuProfiler() = default; 59 60 protected: 61 TracingCpuProfiler() = default; 62 }; 63 64 // TickSample captures the information collected for each sample. 65 struct TickSample { 66 // Internal profiling (with --prof + tools/$OS-tick-processor) wants to 67 // include the runtime function we're calling. Externally exposed tick 68 // samples don't care. 69 enum RecordCEntryFrame { kIncludeCEntryFrame, kSkipCEntryFrame }; 70 TickSampleTickSample71 TickSample() 72 : state(OTHER), 73 pc(nullptr), 74 external_callback_entry(nullptr), 75 frames_count(0), 76 has_external_callback(false), 77 update_stats(true) {} 78 79 /** 80 * Initialize a tick sample from the isolate. 81 * \param isolate The isolate. 82 * \param state Execution state. 83 * \param record_c_entry_frame Include or skip the runtime function. 84 * \param update_stats Whether update the sample to the aggregated stats. 85 * \param use_simulator_reg_state When set to true and V8 is running under a 86 * simulator, the method will use the simulator 87 * register state rather than the one provided 88 * with |state| argument. Otherwise the method 89 * will use provided register |state| as is. 90 */ 91 void Init(Isolate* isolate, const v8::RegisterState& state, 92 RecordCEntryFrame record_c_entry_frame, bool update_stats, 93 bool use_simulator_reg_state = true); 94 /** 95 * Get a call stack sample from the isolate. 96 * \param isolate The isolate. 97 * \param state Register state. 98 * \param record_c_entry_frame Include or skip the runtime function. 99 * \param frames Caller allocated buffer to store stack frames. 100 * \param frames_limit Maximum number of frames to capture. The buffer must 101 * be large enough to hold the number of frames. 102 * \param sample_info The sample info is filled up by the function 103 * provides number of actual captured stack frames and 104 * the current VM state. 105 * \param use_simulator_reg_state When set to true and V8 is running under a 106 * simulator, the method will use the simulator 107 * register state rather than the one provided 108 * with |state| argument. Otherwise the method 109 * will use provided register |state| as is. 110 * \note GetStackSample is thread and signal safe and should only be called 111 * when the JS thread is paused or interrupted. 112 * Otherwise the behavior is undefined. 113 */ 114 static bool GetStackSample(Isolate* isolate, v8::RegisterState* state, 115 RecordCEntryFrame record_c_entry_frame, 116 void** frames, size_t frames_limit, 117 v8::SampleInfo* sample_info, 118 bool use_simulator_reg_state = true); 119 StateTag state; // The state of the VM. 120 void* pc; // Instruction pointer. 121 union { 122 void* tos; // Top stack value (*sp). 123 void* external_callback_entry; 124 }; 125 static const unsigned kMaxFramesCountLog2 = 8; 126 static const unsigned kMaxFramesCount = (1 << kMaxFramesCountLog2) - 1; 127 void* stack[kMaxFramesCount]; // Call stack. 128 unsigned frames_count : kMaxFramesCountLog2; // Number of captured frames. 129 bool has_external_callback : 1; 130 bool update_stats : 1; // Whether the sample should update aggregated stats. 131 }; 132 133 /** 134 * CpuProfileNode represents a node in a call graph. 135 */ 136 class V8_EXPORT CpuProfileNode { 137 public: 138 struct LineTick { 139 /** The 1-based number of the source line where the function originates. */ 140 int line; 141 142 /** The count of samples associated with the source line. */ 143 unsigned int hit_count; 144 }; 145 146 /** Returns function name (empty string for anonymous functions.) */ 147 Local<String> GetFunctionName() const; 148 149 /** 150 * Returns function name (empty string for anonymous functions.) 151 * The string ownership is *not* passed to the caller. It stays valid until 152 * profile is deleted. The function is thread safe. 153 */ 154 const char* GetFunctionNameStr() const; 155 156 /** Returns id of the script where function is located. */ 157 int GetScriptId() const; 158 159 /** Returns resource name for script from where the function originates. */ 160 Local<String> GetScriptResourceName() const; 161 162 /** 163 * Returns resource name for script from where the function originates. 164 * The string ownership is *not* passed to the caller. It stays valid until 165 * profile is deleted. The function is thread safe. 166 */ 167 const char* GetScriptResourceNameStr() const; 168 169 /** 170 * Returns the number, 1-based, of the line where the function originates. 171 * kNoLineNumberInfo if no line number information is available. 172 */ 173 int GetLineNumber() const; 174 175 /** 176 * Returns 1-based number of the column where the function originates. 177 * kNoColumnNumberInfo if no column number information is available. 178 */ 179 int GetColumnNumber() const; 180 181 /** 182 * Returns the number of the function's source lines that collect the samples. 183 */ 184 unsigned int GetHitLineCount() const; 185 186 /** Returns the set of source lines that collect the samples. 187 * The caller allocates buffer and responsible for releasing it. 188 * True if all available entries are copied, otherwise false. 189 * The function copies nothing if buffer is not large enough. 190 */ 191 bool GetLineTicks(LineTick* entries, unsigned int length) const; 192 193 /** Returns bailout reason for the function 194 * if the optimization was disabled for it. 195 */ 196 const char* GetBailoutReason() const; 197 198 /** 199 * Returns the count of samples where the function was currently executing. 200 */ 201 unsigned GetHitCount() const; 202 203 /** Returns function entry UID. */ 204 V8_DEPRECATE_SOON( 205 "Use GetScriptId, GetLineNumber, and GetColumnNumber instead.", 206 unsigned GetCallUid() const); 207 208 /** Returns id of the node. The id is unique within the tree */ 209 unsigned GetNodeId() const; 210 211 /** Returns child nodes count of the node. */ 212 int GetChildrenCount() const; 213 214 /** Retrieves a child node by index. */ 215 const CpuProfileNode* GetChild(int index) const; 216 217 /** Retrieves deopt infos for the node. */ 218 const std::vector<CpuProfileDeoptInfo>& GetDeoptInfos() const; 219 220 static const int kNoLineNumberInfo = Message::kNoLineNumberInfo; 221 static const int kNoColumnNumberInfo = Message::kNoColumnInfo; 222 }; 223 224 225 /** 226 * CpuProfile contains a CPU profile in a form of top-down call tree 227 * (from main() down to functions that do all the work). 228 */ 229 class V8_EXPORT CpuProfile { 230 public: 231 /** Returns CPU profile title. */ 232 Local<String> GetTitle() const; 233 234 /** Returns the root node of the top down call tree. */ 235 const CpuProfileNode* GetTopDownRoot() const; 236 237 /** 238 * Returns number of samples recorded. The samples are not recorded unless 239 * |record_samples| parameter of CpuProfiler::StartCpuProfiling is true. 240 */ 241 int GetSamplesCount() const; 242 243 /** 244 * Returns profile node corresponding to the top frame the sample at 245 * the given index. 246 */ 247 const CpuProfileNode* GetSample(int index) const; 248 249 /** 250 * Returns the timestamp of the sample. The timestamp is the number of 251 * microseconds since some unspecified starting point. 252 * The point is equal to the starting point used by GetStartTime. 253 */ 254 int64_t GetSampleTimestamp(int index) const; 255 256 /** 257 * Returns time when the profile recording was started (in microseconds) 258 * since some unspecified starting point. 259 */ 260 int64_t GetStartTime() const; 261 262 /** 263 * Returns time when the profile recording was stopped (in microseconds) 264 * since some unspecified starting point. 265 * The point is equal to the starting point used by GetStartTime. 266 */ 267 int64_t GetEndTime() const; 268 269 /** 270 * Deletes the profile and removes it from CpuProfiler's list. 271 * All pointers to nodes previously returned become invalid. 272 */ 273 void Delete(); 274 }; 275 276 enum CpuProfilingMode { 277 // In the resulting CpuProfile tree, intermediate nodes in a stack trace 278 // (from the root to a leaf) will have line numbers that point to the start 279 // line of the function, rather than the line of the callsite of the child. 280 kLeafNodeLineNumbers, 281 // In the resulting CpuProfile tree, nodes are separated based on the line 282 // number of their callsite in their parent. 283 kCallerLineNumbers, 284 }; 285 286 /** 287 * Interface for controlling CPU profiling. Instance of the 288 * profiler can be created using v8::CpuProfiler::New method. 289 */ 290 class V8_EXPORT CpuProfiler { 291 public: 292 /** 293 * Creates a new CPU profiler for the |isolate|. The isolate must be 294 * initialized. The profiler object must be disposed after use by calling 295 * |Dispose| method. 296 */ 297 static CpuProfiler* New(Isolate* isolate); 298 299 /** 300 * Synchronously collect current stack sample in all profilers attached to 301 * the |isolate|. The call does not affect number of ticks recorded for 302 * the current top node. 303 */ 304 static void CollectSample(Isolate* isolate); 305 306 /** 307 * Disposes the CPU profiler object. 308 */ 309 void Dispose(); 310 311 /** 312 * Changes default CPU profiler sampling interval to the specified number 313 * of microseconds. Default interval is 1000us. This method must be called 314 * when there are no profiles being recorded. 315 */ 316 void SetSamplingInterval(int us); 317 318 /** 319 * Starts collecting CPU profile. Title may be an empty string. It 320 * is allowed to have several profiles being collected at 321 * once. Attempts to start collecting several profiles with the same 322 * title are silently ignored. While collecting a profile, functions 323 * from all security contexts are included in it. The token-based 324 * filtering is only performed when querying for a profile. 325 * 326 * |record_samples| parameter controls whether individual samples should 327 * be recorded in addition to the aggregated tree. 328 */ 329 void StartProfiling(Local<String> title, CpuProfilingMode mode, 330 bool record_samples = false); 331 /** 332 * The same as StartProfiling above, but the CpuProfilingMode defaults to 333 * kLeafNodeLineNumbers mode, which was the previous default behavior of the 334 * profiler. 335 */ 336 void StartProfiling(Local<String> title, bool record_samples = false); 337 338 /** 339 * Stops collecting CPU profile with a given title and returns it. 340 * If the title given is empty, finishes the last profile started. 341 */ 342 CpuProfile* StopProfiling(Local<String> title); 343 344 /** 345 * Force collection of a sample. Must be called on the VM thread. 346 * Recording the forced sample does not contribute to the aggregated 347 * profile statistics. 348 */ 349 V8_DEPRECATED("Use static CollectSample(Isolate*) instead.", 350 void CollectSample()); 351 352 /** 353 * Tells the profiler whether the embedder is idle. 354 */ 355 V8_DEPRECATED("Use Isolate::SetIdle(bool) instead.", 356 void SetIdle(bool is_idle)); 357 358 private: 359 CpuProfiler(); 360 ~CpuProfiler(); 361 CpuProfiler(const CpuProfiler&); 362 CpuProfiler& operator=(const CpuProfiler&); 363 }; 364 365 366 /** 367 * HeapSnapshotEdge represents a directed connection between heap 368 * graph nodes: from retainers to retained nodes. 369 */ 370 class V8_EXPORT HeapGraphEdge { 371 public: 372 enum Type { 373 kContextVariable = 0, // A variable from a function context. 374 kElement = 1, // An element of an array. 375 kProperty = 2, // A named object property. 376 kInternal = 3, // A link that can't be accessed from JS, 377 // thus, its name isn't a real property name 378 // (e.g. parts of a ConsString). 379 kHidden = 4, // A link that is needed for proper sizes 380 // calculation, but may be hidden from user. 381 kShortcut = 5, // A link that must not be followed during 382 // sizes calculation. 383 kWeak = 6 // A weak reference (ignored by the GC). 384 }; 385 386 /** Returns edge type (see HeapGraphEdge::Type). */ 387 Type GetType() const; 388 389 /** 390 * Returns edge name. This can be a variable name, an element index, or 391 * a property name. 392 */ 393 Local<Value> GetName() const; 394 395 /** Returns origin node. */ 396 const HeapGraphNode* GetFromNode() const; 397 398 /** Returns destination node. */ 399 const HeapGraphNode* GetToNode() const; 400 }; 401 402 403 /** 404 * HeapGraphNode represents a node in a heap graph. 405 */ 406 class V8_EXPORT HeapGraphNode { 407 public: 408 enum Type { 409 kHidden = 0, // Hidden node, may be filtered when shown to user. 410 kArray = 1, // An array of elements. 411 kString = 2, // A string. 412 kObject = 3, // A JS object (except for arrays and strings). 413 kCode = 4, // Compiled code. 414 kClosure = 5, // Function closure. 415 kRegExp = 6, // RegExp. 416 kHeapNumber = 7, // Number stored in the heap. 417 kNative = 8, // Native object (not from V8 heap). 418 kSynthetic = 9, // Synthetic object, usually used for grouping 419 // snapshot items together. 420 kConsString = 10, // Concatenated string. A pair of pointers to strings. 421 kSlicedString = 11, // Sliced string. A fragment of another string. 422 kSymbol = 12, // A Symbol (ES6). 423 kBigInt = 13 // BigInt. 424 }; 425 426 /** Returns node type (see HeapGraphNode::Type). */ 427 Type GetType() const; 428 429 /** 430 * Returns node name. Depending on node's type this can be the name 431 * of the constructor (for objects), the name of the function (for 432 * closures), string value, or an empty string (for compiled code). 433 */ 434 Local<String> GetName() const; 435 436 /** 437 * Returns node id. For the same heap object, the id remains the same 438 * across all snapshots. 439 */ 440 SnapshotObjectId GetId() const; 441 442 /** Returns node's own size, in bytes. */ 443 size_t GetShallowSize() const; 444 445 /** Returns child nodes count of the node. */ 446 int GetChildrenCount() const; 447 448 /** Retrieves a child by index. */ 449 const HeapGraphEdge* GetChild(int index) const; 450 }; 451 452 453 /** 454 * An interface for exporting data from V8, using "push" model. 455 */ 456 class V8_EXPORT OutputStream { // NOLINT 457 public: 458 enum WriteResult { 459 kContinue = 0, 460 kAbort = 1 461 }; ~OutputStream()462 virtual ~OutputStream() {} 463 /** Notify about the end of stream. */ 464 virtual void EndOfStream() = 0; 465 /** Get preferred output chunk size. Called only once. */ GetChunkSize()466 virtual int GetChunkSize() { return 1024; } 467 /** 468 * Writes the next chunk of snapshot data into the stream. Writing 469 * can be stopped by returning kAbort as function result. EndOfStream 470 * will not be called in case writing was aborted. 471 */ 472 virtual WriteResult WriteAsciiChunk(char* data, int size) = 0; 473 /** 474 * Writes the next chunk of heap stats data into the stream. Writing 475 * can be stopped by returning kAbort as function result. EndOfStream 476 * will not be called in case writing was aborted. 477 */ WriteHeapStatsChunk(HeapStatsUpdate * data,int count)478 virtual WriteResult WriteHeapStatsChunk(HeapStatsUpdate* data, int count) { 479 return kAbort; 480 } 481 }; 482 483 484 /** 485 * HeapSnapshots record the state of the JS heap at some moment. 486 */ 487 class V8_EXPORT HeapSnapshot { 488 public: 489 enum SerializationFormat { 490 kJSON = 0 // See format description near 'Serialize' method. 491 }; 492 493 /** Returns the root node of the heap graph. */ 494 const HeapGraphNode* GetRoot() const; 495 496 /** Returns a node by its id. */ 497 const HeapGraphNode* GetNodeById(SnapshotObjectId id) const; 498 499 /** Returns total nodes count in the snapshot. */ 500 int GetNodesCount() const; 501 502 /** Returns a node by index. */ 503 const HeapGraphNode* GetNode(int index) const; 504 505 /** Returns a max seen JS object Id. */ 506 SnapshotObjectId GetMaxSnapshotJSObjectId() const; 507 508 /** 509 * Deletes the snapshot and removes it from HeapProfiler's list. 510 * All pointers to nodes, edges and paths previously returned become 511 * invalid. 512 */ 513 void Delete(); 514 515 /** 516 * Prepare a serialized representation of the snapshot. The result 517 * is written into the stream provided in chunks of specified size. 518 * The total length of the serialized snapshot is unknown in 519 * advance, it can be roughly equal to JS heap size (that means, 520 * it can be really big - tens of megabytes). 521 * 522 * For the JSON format, heap contents are represented as an object 523 * with the following structure: 524 * 525 * { 526 * snapshot: { 527 * title: "...", 528 * uid: nnn, 529 * meta: { meta-info }, 530 * node_count: nnn, 531 * edge_count: nnn 532 * }, 533 * nodes: [nodes array], 534 * edges: [edges array], 535 * strings: [strings array] 536 * } 537 * 538 * Nodes reference strings, other nodes, and edges by their indexes 539 * in corresponding arrays. 540 */ 541 void Serialize(OutputStream* stream, 542 SerializationFormat format = kJSON) const; 543 }; 544 545 546 /** 547 * An interface for reporting progress and controlling long-running 548 * activities. 549 */ 550 class V8_EXPORT ActivityControl { // NOLINT 551 public: 552 enum ControlOption { 553 kContinue = 0, 554 kAbort = 1 555 }; ~ActivityControl()556 virtual ~ActivityControl() {} 557 /** 558 * Notify about current progress. The activity can be stopped by 559 * returning kAbort as the callback result. 560 */ 561 virtual ControlOption ReportProgressValue(int done, int total) = 0; 562 }; 563 564 565 /** 566 * AllocationProfile is a sampled profile of allocations done by the program. 567 * This is structured as a call-graph. 568 */ 569 class V8_EXPORT AllocationProfile { 570 public: 571 struct Allocation { 572 /** 573 * Size of the sampled allocation object. 574 */ 575 size_t size; 576 577 /** 578 * The number of objects of such size that were sampled. 579 */ 580 unsigned int count; 581 }; 582 583 /** 584 * Represents a node in the call-graph. 585 */ 586 struct Node { 587 /** 588 * Name of the function. May be empty for anonymous functions or if the 589 * script corresponding to this function has been unloaded. 590 */ 591 Local<String> name; 592 593 /** 594 * Name of the script containing the function. May be empty if the script 595 * name is not available, or if the script has been unloaded. 596 */ 597 Local<String> script_name; 598 599 /** 600 * id of the script where the function is located. May be equal to 601 * v8::UnboundScript::kNoScriptId in cases where the script doesn't exist. 602 */ 603 int script_id; 604 605 /** 606 * Start position of the function in the script. 607 */ 608 int start_position; 609 610 /** 611 * 1-indexed line number where the function starts. May be 612 * kNoLineNumberInfo if no line number information is available. 613 */ 614 int line_number; 615 616 /** 617 * 1-indexed column number where the function starts. May be 618 * kNoColumnNumberInfo if no line number information is available. 619 */ 620 int column_number; 621 622 /** 623 * List of callees called from this node for which we have sampled 624 * allocations. The lifetime of the children is scoped to the containing 625 * AllocationProfile. 626 */ 627 std::vector<Node*> children; 628 629 /** 630 * List of self allocations done by this node in the call-graph. 631 */ 632 std::vector<Allocation> allocations; 633 }; 634 635 /** 636 * Returns the root node of the call-graph. The root node corresponds to an 637 * empty JS call-stack. The lifetime of the returned Node* is scoped to the 638 * containing AllocationProfile. 639 */ 640 virtual Node* GetRootNode() = 0; 641 ~AllocationProfile()642 virtual ~AllocationProfile() {} 643 644 static const int kNoLineNumberInfo = Message::kNoLineNumberInfo; 645 static const int kNoColumnNumberInfo = Message::kNoColumnInfo; 646 }; 647 648 /** 649 * An object graph consisting of embedder objects and V8 objects. 650 * Edges of the graph are strong references between the objects. 651 * The embedder can build this graph during heap snapshot generation 652 * to include the embedder objects in the heap snapshot. 653 * Usage: 654 * 1) Define derived class of EmbedderGraph::Node for embedder objects. 655 * 2) Set the build embedder graph callback on the heap profiler using 656 * HeapProfiler::AddBuildEmbedderGraphCallback. 657 * 3) In the callback use graph->AddEdge(node1, node2) to add an edge from 658 * node1 to node2. 659 * 4) To represent references from/to V8 object, construct V8 nodes using 660 * graph->V8Node(value). 661 */ 662 class V8_EXPORT EmbedderGraph { 663 public: 664 class Node { 665 public: 666 Node() = default; 667 virtual ~Node() = default; 668 virtual const char* Name() = 0; 669 virtual size_t SizeInBytes() = 0; 670 /** 671 * The corresponding V8 wrapper node if not null. 672 * During heap snapshot generation the embedder node and the V8 wrapper 673 * node will be merged into one node to simplify retaining paths. 674 */ WrapperNode()675 virtual Node* WrapperNode() { return nullptr; } IsRootNode()676 virtual bool IsRootNode() { return false; } 677 /** Must return true for non-V8 nodes. */ IsEmbedderNode()678 virtual bool IsEmbedderNode() { return true; } 679 /** 680 * Optional name prefix. It is used in Chrome for tagging detached nodes. 681 */ NamePrefix()682 virtual const char* NamePrefix() { return nullptr; } 683 684 private: 685 Node(const Node&) = delete; 686 Node& operator=(const Node&) = delete; 687 }; 688 689 /** 690 * Returns a node corresponding to the given V8 value. Ownership is not 691 * transferred. The result pointer is valid while the graph is alive. 692 */ 693 virtual Node* V8Node(const v8::Local<v8::Value>& value) = 0; 694 695 /** 696 * Adds the given node to the graph and takes ownership of the node. 697 * Returns a raw pointer to the node that is valid while the graph is alive. 698 */ 699 virtual Node* AddNode(std::unique_ptr<Node> node) = 0; 700 701 /** 702 * Adds an edge that represents a strong reference from the given node 703 * |from| to the given node |to|. The nodes must be added to the graph 704 * before calling this function. 705 */ 706 virtual void AddEdge(Node* from, Node* to) = 0; 707 708 virtual ~EmbedderGraph() = default; 709 }; 710 711 /** 712 * Interface for controlling heap profiling. Instance of the 713 * profiler can be retrieved using v8::Isolate::GetHeapProfiler. 714 */ 715 class V8_EXPORT HeapProfiler { 716 public: 717 enum SamplingFlags { 718 kSamplingNoFlags = 0, 719 kSamplingForceGC = 1 << 0, 720 }; 721 722 typedef std::unordered_set<const v8::PersistentBase<v8::Value>*> 723 RetainerChildren; 724 typedef std::vector<std::pair<v8::RetainedObjectInfo*, RetainerChildren>> 725 RetainerGroups; 726 typedef std::vector<std::pair<const v8::PersistentBase<v8::Value>*, 727 const v8::PersistentBase<v8::Value>*>> 728 RetainerEdges; 729 730 struct RetainerInfos { 731 RetainerGroups groups; 732 RetainerEdges edges; 733 }; 734 735 /** 736 * Callback function invoked to retrieve all RetainerInfos from the embedder. 737 */ 738 typedef RetainerInfos (*GetRetainerInfosCallback)(v8::Isolate* isolate); 739 740 /** 741 * Callback function invoked for obtaining RetainedObjectInfo for 742 * the given JavaScript wrapper object. It is prohibited to enter V8 743 * while the callback is running: only getters on the handle and 744 * GetPointerFromInternalField on the objects are allowed. 745 */ 746 typedef RetainedObjectInfo* (*WrapperInfoCallback)(uint16_t class_id, 747 Local<Value> wrapper); 748 749 /** 750 * Callback function invoked during heap snapshot generation to retrieve 751 * the embedder object graph. The callback should use graph->AddEdge(..) to 752 * add references between the objects. 753 * The callback must not trigger garbage collection in V8. 754 */ 755 typedef void (*BuildEmbedderGraphCallback)(v8::Isolate* isolate, 756 v8::EmbedderGraph* graph, 757 void* data); 758 759 /** TODO(addaleax): Remove */ 760 typedef void (*LegacyBuildEmbedderGraphCallback)(v8::Isolate* isolate, 761 v8::EmbedderGraph* graph); 762 763 /** Returns the number of snapshots taken. */ 764 int GetSnapshotCount(); 765 766 /** Returns a snapshot by index. */ 767 const HeapSnapshot* GetHeapSnapshot(int index); 768 769 /** 770 * Returns SnapshotObjectId for a heap object referenced by |value| if 771 * it has been seen by the heap profiler, kUnknownObjectId otherwise. 772 */ 773 SnapshotObjectId GetObjectId(Local<Value> value); 774 775 /** 776 * Returns heap object with given SnapshotObjectId if the object is alive, 777 * otherwise empty handle is returned. 778 */ 779 Local<Value> FindObjectById(SnapshotObjectId id); 780 781 /** 782 * Clears internal map from SnapshotObjectId to heap object. The new objects 783 * will not be added into it unless a heap snapshot is taken or heap object 784 * tracking is kicked off. 785 */ 786 void ClearObjectIds(); 787 788 /** 789 * A constant for invalid SnapshotObjectId. GetSnapshotObjectId will return 790 * it in case heap profiler cannot find id for the object passed as 791 * parameter. HeapSnapshot::GetNodeById will always return NULL for such id. 792 */ 793 static const SnapshotObjectId kUnknownObjectId = 0; 794 795 /** 796 * Callback interface for retrieving user friendly names of global objects. 797 */ 798 class ObjectNameResolver { 799 public: 800 /** 801 * Returns name to be used in the heap snapshot for given node. Returned 802 * string must stay alive until snapshot collection is completed. 803 */ 804 virtual const char* GetName(Local<Object> object) = 0; 805 806 protected: ~ObjectNameResolver()807 virtual ~ObjectNameResolver() {} 808 }; 809 810 /** 811 * Takes a heap snapshot and returns it. 812 */ 813 const HeapSnapshot* TakeHeapSnapshot( 814 ActivityControl* control = NULL, 815 ObjectNameResolver* global_object_name_resolver = NULL); 816 817 /** 818 * Starts tracking of heap objects population statistics. After calling 819 * this method, all heap objects relocations done by the garbage collector 820 * are being registered. 821 * 822 * |track_allocations| parameter controls whether stack trace of each 823 * allocation in the heap will be recorded and reported as part of 824 * HeapSnapshot. 825 */ 826 void StartTrackingHeapObjects(bool track_allocations = false); 827 828 /** 829 * Adds a new time interval entry to the aggregated statistics array. The 830 * time interval entry contains information on the current heap objects 831 * population size. The method also updates aggregated statistics and 832 * reports updates for all previous time intervals via the OutputStream 833 * object. Updates on each time interval are provided as a stream of the 834 * HeapStatsUpdate structure instances. 835 * If |timestamp_us| is supplied, timestamp of the new entry will be written 836 * into it. The return value of the function is the last seen heap object Id. 837 * 838 * StartTrackingHeapObjects must be called before the first call to this 839 * method. 840 */ 841 SnapshotObjectId GetHeapStats(OutputStream* stream, 842 int64_t* timestamp_us = NULL); 843 844 /** 845 * Stops tracking of heap objects population statistics, cleans up all 846 * collected data. StartHeapObjectsTracking must be called again prior to 847 * calling GetHeapStats next time. 848 */ 849 void StopTrackingHeapObjects(); 850 851 /** 852 * Starts gathering a sampling heap profile. A sampling heap profile is 853 * similar to tcmalloc's heap profiler and Go's mprof. It samples object 854 * allocations and builds an online 'sampling' heap profile. At any point in 855 * time, this profile is expected to be a representative sample of objects 856 * currently live in the system. Each sampled allocation includes the stack 857 * trace at the time of allocation, which makes this really useful for memory 858 * leak detection. 859 * 860 * This mechanism is intended to be cheap enough that it can be used in 861 * production with minimal performance overhead. 862 * 863 * Allocations are sampled using a randomized Poisson process. On average, one 864 * allocation will be sampled every |sample_interval| bytes allocated. The 865 * |stack_depth| parameter controls the maximum number of stack frames to be 866 * captured on each allocation. 867 * 868 * NOTE: This is a proof-of-concept at this point. Right now we only sample 869 * newspace allocations. Support for paged space allocation (e.g. pre-tenured 870 * objects, large objects, code objects, etc.) and native allocations 871 * doesn't exist yet, but is anticipated in the future. 872 * 873 * Objects allocated before the sampling is started will not be included in 874 * the profile. 875 * 876 * Returns false if a sampling heap profiler is already running. 877 */ 878 bool StartSamplingHeapProfiler(uint64_t sample_interval = 512 * 1024, 879 int stack_depth = 16, 880 SamplingFlags flags = kSamplingNoFlags); 881 882 /** 883 * Stops the sampling heap profile and discards the current profile. 884 */ 885 void StopSamplingHeapProfiler(); 886 887 /** 888 * Returns the sampled profile of allocations allocated (and still live) since 889 * StartSamplingHeapProfiler was called. The ownership of the pointer is 890 * transferred to the caller. Returns nullptr if sampling heap profiler is not 891 * active. 892 */ 893 AllocationProfile* GetAllocationProfile(); 894 895 /** 896 * Deletes all snapshots taken. All previously returned pointers to 897 * snapshots and their contents become invalid after this call. 898 */ 899 void DeleteAllHeapSnapshots(); 900 901 /** Binds a callback to embedder's class ID. */ 902 V8_DEPRECATED( 903 "Use AddBuildEmbedderGraphCallback to provide info about embedder nodes", 904 void SetWrapperClassInfoProvider(uint16_t class_id, 905 WrapperInfoCallback callback)); 906 907 V8_DEPRECATED( 908 "Use AddBuildEmbedderGraphCallback to provide info about embedder nodes", 909 void SetGetRetainerInfosCallback(GetRetainerInfosCallback callback)); 910 911 V8_DEPRECATE_SOON( 912 "Use AddBuildEmbedderGraphCallback to provide info about embedder nodes", 913 void SetBuildEmbedderGraphCallback( 914 LegacyBuildEmbedderGraphCallback callback)); 915 void AddBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback, 916 void* data); 917 void RemoveBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback, 918 void* data); 919 920 /** 921 * Default value of persistent handle class ID. Must not be used to 922 * define a class. Can be used to reset a class of a persistent 923 * handle. 924 */ 925 static const uint16_t kPersistentHandleNoClassId = 0; 926 927 private: 928 HeapProfiler(); 929 ~HeapProfiler(); 930 HeapProfiler(const HeapProfiler&); 931 HeapProfiler& operator=(const HeapProfiler&); 932 }; 933 934 /** 935 * Interface for providing information about embedder's objects 936 * held by global handles. This information is reported in two ways: 937 * 938 * 1. When calling AddObjectGroup, an embedder may pass 939 * RetainedObjectInfo instance describing the group. To collect 940 * this information while taking a heap snapshot, V8 calls GC 941 * prologue and epilogue callbacks. 942 * 943 * 2. When a heap snapshot is collected, V8 additionally 944 * requests RetainedObjectInfos for persistent handles that 945 * were not previously reported via AddObjectGroup. 946 * 947 * Thus, if an embedder wants to provide information about native 948 * objects for heap snapshots, it can do it in a GC prologue 949 * handler, and / or by assigning wrapper class ids in the following way: 950 * 951 * 1. Bind a callback to class id by calling SetWrapperClassInfoProvider. 952 * 2. Call SetWrapperClassId on certain persistent handles. 953 * 954 * V8 takes ownership of RetainedObjectInfo instances passed to it and 955 * keeps them alive only during snapshot collection. Afterwards, they 956 * are freed by calling the Dispose class function. 957 */ 958 class V8_EXPORT RetainedObjectInfo { // NOLINT 959 public: 960 /** Called by V8 when it no longer needs an instance. */ 961 virtual void Dispose() = 0; 962 963 /** Returns whether two instances are equivalent. */ 964 virtual bool IsEquivalent(RetainedObjectInfo* other) = 0; 965 966 /** 967 * Returns hash value for the instance. Equivalent instances 968 * must have the same hash value. 969 */ 970 virtual intptr_t GetHash() = 0; 971 972 /** 973 * Returns human-readable label. It must be a null-terminated UTF-8 974 * encoded string. V8 copies its contents during a call to GetLabel. 975 */ 976 virtual const char* GetLabel() = 0; 977 978 /** 979 * Returns human-readable group label. It must be a null-terminated UTF-8 980 * encoded string. V8 copies its contents during a call to GetGroupLabel. 981 * Heap snapshot generator will collect all the group names, create 982 * top level entries with these names and attach the objects to the 983 * corresponding top level group objects. There is a default 984 * implementation which is required because embedders don't have their 985 * own implementation yet. 986 */ GetGroupLabel()987 virtual const char* GetGroupLabel() { return GetLabel(); } 988 989 /** 990 * Returns element count in case if a global handle retains 991 * a subgraph by holding one of its nodes. 992 */ GetElementCount()993 virtual intptr_t GetElementCount() { return -1; } 994 995 /** Returns embedder's object size in bytes. */ GetSizeInBytes()996 virtual intptr_t GetSizeInBytes() { return -1; } 997 998 protected: RetainedObjectInfo()999 RetainedObjectInfo() {} ~RetainedObjectInfo()1000 virtual ~RetainedObjectInfo() {} 1001 1002 private: 1003 RetainedObjectInfo(const RetainedObjectInfo&); 1004 RetainedObjectInfo& operator=(const RetainedObjectInfo&); 1005 }; 1006 1007 1008 /** 1009 * A struct for exporting HeapStats data from V8, using "push" model. 1010 * See HeapProfiler::GetHeapStats. 1011 */ 1012 struct HeapStatsUpdate { HeapStatsUpdateHeapStatsUpdate1013 HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size) 1014 : index(index), count(count), size(size) { } 1015 uint32_t index; // Index of the time interval that was changed. 1016 uint32_t count; // New value of count field for the interval with this index. 1017 uint32_t size; // New value of size field for the interval with this index. 1018 }; 1019 1020 #define CODE_EVENTS_LIST(V) \ 1021 V(Builtin) \ 1022 V(Callback) \ 1023 V(Eval) \ 1024 V(Function) \ 1025 V(InterpretedFunction) \ 1026 V(Handler) \ 1027 V(BytecodeHandler) \ 1028 V(LazyCompile) \ 1029 V(RegExp) \ 1030 V(Script) \ 1031 V(Stub) 1032 1033 /** 1034 * Note that this enum may be extended in the future. Please include a default 1035 * case if this enum is used in a switch statement. 1036 */ 1037 enum CodeEventType { 1038 kUnknownType = 0 1039 #define V(Name) , k##Name##Type 1040 CODE_EVENTS_LIST(V) 1041 #undef V 1042 }; 1043 1044 /** 1045 * Representation of a code creation event 1046 */ 1047 class V8_EXPORT CodeEvent { 1048 public: 1049 uintptr_t GetCodeStartAddress(); 1050 size_t GetCodeSize(); 1051 Local<String> GetFunctionName(); 1052 Local<String> GetScriptName(); 1053 int GetScriptLine(); 1054 int GetScriptColumn(); 1055 /** 1056 * NOTE (mmarchini): We can't allocate objects in the heap when we collect 1057 * existing code, and both the code type and the comment are not stored in the 1058 * heap, so we return those as const char*. 1059 */ 1060 CodeEventType GetCodeType(); 1061 const char* GetComment(); 1062 1063 static const char* GetCodeEventTypeName(CodeEventType code_event_type); 1064 }; 1065 1066 /** 1067 * Interface to listen to code creation events. 1068 */ 1069 class V8_EXPORT CodeEventHandler { 1070 public: 1071 /** 1072 * Creates a new listener for the |isolate|. The isolate must be initialized. 1073 * The listener object must be disposed after use by calling |Dispose| method. 1074 * Multiple listeners can be created for the same isolate. 1075 */ 1076 explicit CodeEventHandler(Isolate* isolate); 1077 virtual ~CodeEventHandler(); 1078 1079 virtual void Handle(CodeEvent* code_event) = 0; 1080 1081 void Enable(); 1082 void Disable(); 1083 1084 private: 1085 CodeEventHandler(); 1086 CodeEventHandler(const CodeEventHandler&); 1087 CodeEventHandler& operator=(const CodeEventHandler&); 1088 void* internal_listener_; 1089 }; 1090 1091 } // namespace v8 1092 1093 1094 #endif // V8_V8_PROFILER_H_ 1095