Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 1 | // Copyright 2010 the V8 project authors. All rights reserved. |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 2 | // Use of this source code is governed by a BSD-style license that can be |
| 3 | // found in the LICENSE file. |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 4 | |
| 5 | #ifndef V8_V8_PROFILER_H_ |
| 6 | #define V8_V8_PROFILER_H_ |
| 7 | |
| 8 | #include "v8.h" |
| 9 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 10 | /** |
| 11 | * Profiler support for the V8 JavaScript engine. |
| 12 | */ |
| 13 | namespace v8 { |
| 14 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 15 | class HeapGraphNode; |
| 16 | struct HeapStatsUpdate; |
| 17 | |
| 18 | typedef uint32_t SnapshotObjectId; |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 19 | |
| 20 | /** |
| 21 | * CpuProfileNode represents a node in a call graph. |
| 22 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 23 | class V8_EXPORT CpuProfileNode { |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 24 | public: |
Emily Bernier | d0a1eb7 | 2015-03-24 16:35:39 -0400 | [diff] [blame^] | 25 | struct LineTick { |
| 26 | /** The 1-based number of the source line where the function originates. */ |
| 27 | int line; |
| 28 | |
| 29 | /** The count of samples associated with the source line. */ |
| 30 | unsigned int hit_count; |
| 31 | }; |
| 32 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 33 | /** Returns function name (empty string for anonymous functions.) */ |
| 34 | Handle<String> GetFunctionName() const; |
| 35 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 36 | /** Returns id of the script where function is located. */ |
| 37 | int GetScriptId() const; |
| 38 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 39 | /** Returns resource name for script from where the function originates. */ |
| 40 | Handle<String> GetScriptResourceName() const; |
| 41 | |
| 42 | /** |
| 43 | * Returns the number, 1-based, of the line where the function originates. |
| 44 | * kNoLineNumberInfo if no line number information is available. |
| 45 | */ |
| 46 | int GetLineNumber() const; |
| 47 | |
| 48 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 49 | * Returns 1-based number of the column where the function originates. |
| 50 | * kNoColumnNumberInfo if no column number information is available. |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 51 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 52 | int GetColumnNumber() const; |
| 53 | |
Emily Bernier | d0a1eb7 | 2015-03-24 16:35:39 -0400 | [diff] [blame^] | 54 | /** |
| 55 | * Returns the number of the function's source lines that collect the samples. |
| 56 | */ |
| 57 | unsigned int GetHitLineCount() const; |
| 58 | |
| 59 | /** Returns the set of source lines that collect the samples. |
| 60 | * The caller allocates buffer and responsible for releasing it. |
| 61 | * True if all available entries are copied, otherwise false. |
| 62 | * The function copies nothing if buffer is not large enough. |
| 63 | */ |
| 64 | bool GetLineTicks(LineTick* entries, unsigned int length) const; |
| 65 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 66 | /** Returns bailout reason for the function |
| 67 | * if the optimization was disabled for it. |
| 68 | */ |
| 69 | const char* GetBailoutReason() const; |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 70 | |
| 71 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 72 | * Returns the count of samples where the function was currently executing. |
| 73 | */ |
| 74 | unsigned GetHitCount() const; |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 75 | |
| 76 | /** Returns function entry UID. */ |
| 77 | unsigned GetCallUid() const; |
| 78 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 79 | /** Returns id of the node. The id is unique within the tree */ |
| 80 | unsigned GetNodeId() const; |
| 81 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 82 | /** Returns child nodes count of the node. */ |
| 83 | int GetChildrenCount() const; |
| 84 | |
| 85 | /** Retrieves a child node by index. */ |
| 86 | const CpuProfileNode* GetChild(int index) const; |
| 87 | |
Kristian Monsen | 25f6136 | 2010-05-21 11:50:48 +0100 | [diff] [blame] | 88 | static const int kNoLineNumberInfo = Message::kNoLineNumberInfo; |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 89 | static const int kNoColumnNumberInfo = Message::kNoColumnInfo; |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 90 | }; |
| 91 | |
| 92 | |
| 93 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 94 | * CpuProfile contains a CPU profile in a form of top-down call tree |
| 95 | * (from main() down to functions that do all the work). |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 96 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 97 | class V8_EXPORT CpuProfile { |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 98 | public: |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 99 | /** Returns CPU profile title. */ |
| 100 | Handle<String> GetTitle() const; |
| 101 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 102 | /** Returns the root node of the top down call tree. */ |
| 103 | const CpuProfileNode* GetTopDownRoot() const; |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 104 | |
| 105 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 106 | * Returns number of samples recorded. The samples are not recorded unless |
| 107 | * |record_samples| parameter of CpuProfiler::StartCpuProfiling is true. |
| 108 | */ |
| 109 | int GetSamplesCount() const; |
| 110 | |
| 111 | /** |
| 112 | * Returns profile node corresponding to the top frame the sample at |
| 113 | * the given index. |
| 114 | */ |
| 115 | const CpuProfileNode* GetSample(int index) const; |
| 116 | |
| 117 | /** |
| 118 | * Returns the timestamp of the sample. The timestamp is the number of |
| 119 | * microseconds since some unspecified starting point. |
| 120 | * The point is equal to the starting point used by GetStartTime. |
| 121 | */ |
| 122 | int64_t GetSampleTimestamp(int index) const; |
| 123 | |
| 124 | /** |
| 125 | * Returns time when the profile recording was started (in microseconds) |
| 126 | * since some unspecified starting point. |
| 127 | */ |
| 128 | int64_t GetStartTime() const; |
| 129 | |
| 130 | /** |
| 131 | * Returns time when the profile recording was stopped (in microseconds) |
| 132 | * since some unspecified starting point. |
| 133 | * The point is equal to the starting point used by GetStartTime. |
| 134 | */ |
| 135 | int64_t GetEndTime() const; |
| 136 | |
| 137 | /** |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 138 | * Deletes the profile and removes it from CpuProfiler's list. |
| 139 | * All pointers to nodes previously returned become invalid. |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 140 | */ |
| 141 | void Delete(); |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 142 | }; |
| 143 | |
| 144 | |
| 145 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 146 | * Interface for controlling CPU profiling. Instance of the |
| 147 | * profiler can be retrieved using v8::Isolate::GetCpuProfiler. |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 148 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 149 | class V8_EXPORT CpuProfiler { |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 150 | public: |
| 151 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 152 | * Changes default CPU profiler sampling interval to the specified number |
| 153 | * of microseconds. Default interval is 1000us. This method must be called |
| 154 | * when there are no profiles being recorded. |
Leon Clarke | f7060e2 | 2010-06-03 12:02:55 +0100 | [diff] [blame] | 155 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 156 | void SetSamplingInterval(int us); |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 157 | |
| 158 | /** |
| 159 | * Starts collecting CPU profile. Title may be an empty string. It |
| 160 | * is allowed to have several profiles being collected at |
| 161 | * once. Attempts to start collecting several profiles with the same |
Leon Clarke | f7060e2 | 2010-06-03 12:02:55 +0100 | [diff] [blame] | 162 | * title are silently ignored. While collecting a profile, functions |
| 163 | * from all security contexts are included in it. The token-based |
| 164 | * filtering is only performed when querying for a profile. |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 165 | * |
| 166 | * |record_samples| parameter controls whether individual samples should |
| 167 | * be recorded in addition to the aggregated tree. |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 168 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 169 | void StartProfiling(Handle<String> title, bool record_samples = false); |
| 170 | |
| 171 | /** Deprecated. Use StartProfiling instead. */ |
| 172 | V8_DEPRECATED("Use StartProfiling", |
| 173 | void StartCpuProfiling(Handle<String> title, |
| 174 | bool record_samples = false)); |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 175 | |
| 176 | /** |
| 177 | * Stops collecting CPU profile with a given title and returns it. |
| 178 | * If the title given is empty, finishes the last profile started. |
| 179 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 180 | CpuProfile* StopProfiling(Handle<String> title); |
| 181 | |
| 182 | /** Deprecated. Use StopProfiling instead. */ |
| 183 | V8_DEPRECATED("Use StopProfiling", |
| 184 | const CpuProfile* StopCpuProfiling(Handle<String> title)); |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 185 | |
| 186 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 187 | * Tells the profiler whether the embedder is idle. |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 188 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 189 | void SetIdle(bool is_idle); |
| 190 | |
| 191 | private: |
| 192 | CpuProfiler(); |
| 193 | ~CpuProfiler(); |
| 194 | CpuProfiler(const CpuProfiler&); |
| 195 | CpuProfiler& operator=(const CpuProfiler&); |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 196 | }; |
| 197 | |
| 198 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 199 | /** |
| 200 | * HeapSnapshotEdge represents a directed connection between heap |
Ben Murdoch | 257744e | 2011-11-30 15:57:28 +0000 | [diff] [blame] | 201 | * graph nodes: from retainers to retained nodes. |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 202 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 203 | class V8_EXPORT HeapGraphEdge { |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 204 | public: |
| 205 | enum Type { |
Iain Merrick | 7568138 | 2010-08-19 15:07:18 +0100 | [diff] [blame] | 206 | kContextVariable = 0, // A variable from a function context. |
| 207 | kElement = 1, // An element of an array. |
| 208 | kProperty = 2, // A named object property. |
Shimeng (Simon) Wang | 8a31eba | 2010-12-06 19:01:33 -0800 | [diff] [blame] | 209 | kInternal = 3, // A link that can't be accessed from JS, |
| 210 | // thus, its name isn't a real property name |
| 211 | // (e.g. parts of a ConsString). |
| 212 | kHidden = 4, // A link that is needed for proper sizes |
| 213 | // calculation, but may be hidden from user. |
Ben Murdoch | 3ef787d | 2012-04-12 10:51:47 +0100 | [diff] [blame] | 214 | kShortcut = 5, // A link that must not be followed during |
Shimeng (Simon) Wang | 8a31eba | 2010-12-06 19:01:33 -0800 | [diff] [blame] | 215 | // sizes calculation. |
Ben Murdoch | 3ef787d | 2012-04-12 10:51:47 +0100 | [diff] [blame] | 216 | kWeak = 6 // A weak reference (ignored by the GC). |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 217 | }; |
| 218 | |
| 219 | /** Returns edge type (see HeapGraphEdge::Type). */ |
| 220 | Type GetType() const; |
| 221 | |
| 222 | /** |
| 223 | * Returns edge name. This can be a variable name, an element index, or |
| 224 | * a property name. |
| 225 | */ |
| 226 | Handle<Value> GetName() const; |
| 227 | |
| 228 | /** Returns origin node. */ |
| 229 | const HeapGraphNode* GetFromNode() const; |
| 230 | |
| 231 | /** Returns destination node. */ |
| 232 | const HeapGraphNode* GetToNode() const; |
| 233 | }; |
| 234 | |
| 235 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 236 | /** |
| 237 | * HeapGraphNode represents a node in a heap graph. |
| 238 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 239 | class V8_EXPORT HeapGraphNode { |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 240 | public: |
| 241 | enum Type { |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 242 | kHidden = 0, // Hidden node, may be filtered when shown to user. |
| 243 | kArray = 1, // An array of elements. |
| 244 | kString = 2, // A string. |
| 245 | kObject = 3, // A JS object (except for arrays and strings). |
| 246 | kCode = 4, // Compiled code. |
| 247 | kClosure = 5, // Function closure. |
| 248 | kRegExp = 6, // RegExp. |
| 249 | kHeapNumber = 7, // Number stored in the heap. |
| 250 | kNative = 8, // Native object (not from V8 heap). |
| 251 | kSynthetic = 9, // Synthetic object, usualy used for grouping |
| 252 | // snapshot items together. |
| 253 | kConsString = 10, // Concatenated string. A pair of pointers to strings. |
| 254 | kSlicedString = 11, // Sliced string. A fragment of another string. |
| 255 | kSymbol = 12 // A Symbol (ES6). |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 256 | }; |
| 257 | |
| 258 | /** Returns node type (see HeapGraphNode::Type). */ |
| 259 | Type GetType() const; |
| 260 | |
| 261 | /** |
| 262 | * Returns node name. Depending on node's type this can be the name |
| 263 | * of the constructor (for objects), the name of the function (for |
| 264 | * closures), string value, or an empty string (for compiled code). |
| 265 | */ |
| 266 | Handle<String> GetName() const; |
| 267 | |
Ben Murdoch | 3bec4d2 | 2010-07-22 14:51:16 +0100 | [diff] [blame] | 268 | /** |
| 269 | * Returns node id. For the same heap object, the id remains the same |
Ben Murdoch | 3fb3ca8 | 2011-12-02 17:19:32 +0000 | [diff] [blame] | 270 | * across all snapshots. |
Ben Murdoch | 3bec4d2 | 2010-07-22 14:51:16 +0100 | [diff] [blame] | 271 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 272 | SnapshotObjectId GetId() const; |
Ben Murdoch | 3bec4d2 | 2010-07-22 14:51:16 +0100 | [diff] [blame] | 273 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 274 | /** Returns node's own size, in bytes. */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 275 | V8_DEPRECATED("Use GetShallowSize instead", |
| 276 | int GetSelfSize() const); |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 277 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 278 | /** Returns node's own size, in bytes. */ |
| 279 | size_t GetShallowSize() const; |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 280 | |
| 281 | /** Returns child nodes count of the node. */ |
| 282 | int GetChildrenCount() const; |
| 283 | |
| 284 | /** Retrieves a child by index. */ |
| 285 | const HeapGraphEdge* GetChild(int index) const; |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 286 | }; |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 287 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 288 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 289 | /** |
| 290 | * An interface for exporting data from V8, using "push" model. |
| 291 | */ |
| 292 | class V8_EXPORT OutputStream { // NOLINT |
| 293 | public: |
| 294 | enum WriteResult { |
| 295 | kContinue = 0, |
| 296 | kAbort = 1 |
| 297 | }; |
| 298 | virtual ~OutputStream() {} |
| 299 | /** Notify about the end of stream. */ |
| 300 | virtual void EndOfStream() = 0; |
| 301 | /** Get preferred output chunk size. Called only once. */ |
| 302 | virtual int GetChunkSize() { return 1024; } |
Shimeng (Simon) Wang | 8a31eba | 2010-12-06 19:01:33 -0800 | [diff] [blame] | 303 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 304 | * Writes the next chunk of snapshot data into the stream. Writing |
| 305 | * can be stopped by returning kAbort as function result. EndOfStream |
| 306 | * will not be called in case writing was aborted. |
Shimeng (Simon) Wang | 8a31eba | 2010-12-06 19:01:33 -0800 | [diff] [blame] | 307 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 308 | virtual WriteResult WriteAsciiChunk(char* data, int size) = 0; |
Ben Murdoch | 69a99ed | 2011-11-30 16:03:39 +0000 | [diff] [blame] | 309 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 310 | * Writes the next chunk of heap stats data into the stream. Writing |
| 311 | * can be stopped by returning kAbort as function result. EndOfStream |
| 312 | * will not be called in case writing was aborted. |
Ben Murdoch | 69a99ed | 2011-11-30 16:03:39 +0000 | [diff] [blame] | 313 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 314 | virtual WriteResult WriteHeapStatsChunk(HeapStatsUpdate* data, int count) { |
| 315 | return kAbort; |
| 316 | } |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 317 | }; |
| 318 | |
| 319 | |
| 320 | /** |
| 321 | * HeapSnapshots record the state of the JS heap at some moment. |
| 322 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 323 | class V8_EXPORT HeapSnapshot { |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 324 | public: |
Kristian Monsen | 0d5e116 | 2010-09-30 15:31:59 +0100 | [diff] [blame] | 325 | enum SerializationFormat { |
| 326 | kJSON = 0 // See format description near 'Serialize' method. |
Steve Block | 791712a | 2010-08-27 10:21:07 +0100 | [diff] [blame] | 327 | }; |
| 328 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 329 | /** Returns heap snapshot UID (assigned by the profiler.) */ |
| 330 | unsigned GetUid() const; |
| 331 | |
| 332 | /** Returns heap snapshot title. */ |
| 333 | Handle<String> GetTitle() const; |
| 334 | |
| 335 | /** Returns the root node of the heap graph. */ |
Ben Murdoch | 3bec4d2 | 2010-07-22 14:51:16 +0100 | [diff] [blame] | 336 | const HeapGraphNode* GetRoot() const; |
| 337 | |
Ben Murdoch | b0fe162 | 2011-05-05 13:52:32 +0100 | [diff] [blame] | 338 | /** Returns a node by its id. */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 339 | const HeapGraphNode* GetNodeById(SnapshotObjectId id) const; |
Ben Murdoch | b0fe162 | 2011-05-05 13:52:32 +0100 | [diff] [blame] | 340 | |
Ben Murdoch | 3fb3ca8 | 2011-12-02 17:19:32 +0000 | [diff] [blame] | 341 | /** Returns total nodes count in the snapshot. */ |
| 342 | int GetNodesCount() const; |
| 343 | |
| 344 | /** Returns a node by index. */ |
| 345 | const HeapGraphNode* GetNode(int index) const; |
| 346 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 347 | /** Returns a max seen JS object Id. */ |
| 348 | SnapshotObjectId GetMaxSnapshotJSObjectId() const; |
| 349 | |
Steve Block | 791712a | 2010-08-27 10:21:07 +0100 | [diff] [blame] | 350 | /** |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 351 | * Deletes the snapshot and removes it from HeapProfiler's list. |
| 352 | * All pointers to nodes, edges and paths previously returned become |
| 353 | * invalid. |
Steve Block | 791712a | 2010-08-27 10:21:07 +0100 | [diff] [blame] | 354 | */ |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 355 | void Delete(); |
Kristian Monsen | 0d5e116 | 2010-09-30 15:31:59 +0100 | [diff] [blame] | 356 | |
| 357 | /** |
| 358 | * Prepare a serialized representation of the snapshot. The result |
| 359 | * is written into the stream provided in chunks of specified size. |
| 360 | * The total length of the serialized snapshot is unknown in |
Ben Murdoch | 257744e | 2011-11-30 15:57:28 +0000 | [diff] [blame] | 361 | * advance, it can be roughly equal to JS heap size (that means, |
Kristian Monsen | 0d5e116 | 2010-09-30 15:31:59 +0100 | [diff] [blame] | 362 | * it can be really big - tens of megabytes). |
| 363 | * |
| 364 | * For the JSON format, heap contents are represented as an object |
| 365 | * with the following structure: |
| 366 | * |
| 367 | * { |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 368 | * snapshot: { |
| 369 | * title: "...", |
| 370 | * uid: nnn, |
| 371 | * meta: { meta-info }, |
| 372 | * node_count: nnn, |
| 373 | * edge_count: nnn |
| 374 | * }, |
| 375 | * nodes: [nodes array], |
| 376 | * edges: [edges array], |
| 377 | * strings: [strings array] |
Kristian Monsen | 0d5e116 | 2010-09-30 15:31:59 +0100 | [diff] [blame] | 378 | * } |
| 379 | * |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 380 | * Nodes reference strings, other nodes, and edges by their indexes |
| 381 | * in corresponding arrays. |
Kristian Monsen | 0d5e116 | 2010-09-30 15:31:59 +0100 | [diff] [blame] | 382 | */ |
| 383 | void Serialize(OutputStream* stream, SerializationFormat format) const; |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 384 | }; |
| 385 | |
| 386 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 387 | /** |
| 388 | * An interface for reporting progress and controlling long-running |
| 389 | * activities. |
| 390 | */ |
| 391 | class V8_EXPORT ActivityControl { // NOLINT |
| 392 | public: |
| 393 | enum ControlOption { |
| 394 | kContinue = 0, |
| 395 | kAbort = 1 |
| 396 | }; |
| 397 | virtual ~ActivityControl() {} |
| 398 | /** |
| 399 | * Notify about current progress. The activity can be stopped by |
| 400 | * returning kAbort as the callback result. |
| 401 | */ |
| 402 | virtual ControlOption ReportProgressValue(int done, int total) = 0; |
| 403 | }; |
| 404 | |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 405 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 406 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 407 | * Interface for controlling heap profiling. Instance of the |
| 408 | * profiler can be retrieved using v8::Isolate::GetHeapProfiler. |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 409 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 410 | class V8_EXPORT HeapProfiler { |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 411 | public: |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 412 | /** |
| 413 | * Callback function invoked for obtaining RetainedObjectInfo for |
| 414 | * the given JavaScript wrapper object. It is prohibited to enter V8 |
| 415 | * while the callback is running: only getters on the handle and |
| 416 | * GetPointerFromInternalField on the objects are allowed. |
| 417 | */ |
| 418 | typedef RetainedObjectInfo* (*WrapperInfoCallback) |
| 419 | (uint16_t class_id, Handle<Value> wrapper); |
| 420 | |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 421 | /** Returns the number of snapshots taken. */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 422 | int GetSnapshotCount(); |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 423 | |
| 424 | /** Returns a snapshot by index. */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 425 | const HeapSnapshot* GetHeapSnapshot(int index); |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 426 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 427 | /** |
| 428 | * Returns SnapshotObjectId for a heap object referenced by |value| if |
| 429 | * it has been seen by the heap profiler, kUnknownObjectId otherwise. |
| 430 | */ |
| 431 | SnapshotObjectId GetObjectId(Handle<Value> value); |
| 432 | |
| 433 | /** |
| 434 | * Returns heap object with given SnapshotObjectId if the object is alive, |
| 435 | * otherwise empty handle is returned. |
| 436 | */ |
| 437 | Handle<Value> FindObjectById(SnapshotObjectId id); |
| 438 | |
| 439 | /** |
| 440 | * Clears internal map from SnapshotObjectId to heap object. The new objects |
| 441 | * will not be added into it unless a heap snapshot is taken or heap object |
| 442 | * tracking is kicked off. |
| 443 | */ |
| 444 | void ClearObjectIds(); |
| 445 | |
| 446 | /** |
| 447 | * A constant for invalid SnapshotObjectId. GetSnapshotObjectId will return |
| 448 | * it in case heap profiler cannot find id for the object passed as |
| 449 | * parameter. HeapSnapshot::GetNodeById will always return NULL for such id. |
| 450 | */ |
| 451 | static const SnapshotObjectId kUnknownObjectId = 0; |
| 452 | |
| 453 | /** |
| 454 | * Callback interface for retrieving user friendly names of global objects. |
| 455 | */ |
| 456 | class ObjectNameResolver { |
| 457 | public: |
| 458 | /** |
| 459 | * Returns name to be used in the heap snapshot for given node. Returned |
| 460 | * string must stay alive until snapshot collection is completed. |
| 461 | */ |
| 462 | virtual const char* GetName(Handle<Object> object) = 0; |
| 463 | protected: |
| 464 | virtual ~ObjectNameResolver() {} |
| 465 | }; |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 466 | |
Steve Block | 791712a | 2010-08-27 10:21:07 +0100 | [diff] [blame] | 467 | /** |
| 468 | * Takes a heap snapshot and returns it. Title may be an empty string. |
Steve Block | 791712a | 2010-08-27 10:21:07 +0100 | [diff] [blame] | 469 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 470 | const HeapSnapshot* TakeHeapSnapshot( |
Steve Block | 791712a | 2010-08-27 10:21:07 +0100 | [diff] [blame] | 471 | Handle<String> title, |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 472 | ActivityControl* control = NULL, |
| 473 | ObjectNameResolver* global_object_name_resolver = NULL); |
| 474 | |
| 475 | /** |
| 476 | * Starts tracking of heap objects population statistics. After calling |
| 477 | * this method, all heap objects relocations done by the garbage collector |
| 478 | * are being registered. |
| 479 | * |
| 480 | * |track_allocations| parameter controls whether stack trace of each |
| 481 | * allocation in the heap will be recorded and reported as part of |
| 482 | * HeapSnapshot. |
| 483 | */ |
| 484 | void StartTrackingHeapObjects(bool track_allocations = false); |
| 485 | |
| 486 | /** |
| 487 | * Adds a new time interval entry to the aggregated statistics array. The |
| 488 | * time interval entry contains information on the current heap objects |
| 489 | * population size. The method also updates aggregated statistics and |
| 490 | * reports updates for all previous time intervals via the OutputStream |
| 491 | * object. Updates on each time interval are provided as a stream of the |
| 492 | * HeapStatsUpdate structure instances. |
| 493 | * The return value of the function is the last seen heap object Id. |
| 494 | * |
| 495 | * StartTrackingHeapObjects must be called before the first call to this |
| 496 | * method. |
| 497 | */ |
| 498 | SnapshotObjectId GetHeapStats(OutputStream* stream); |
| 499 | |
| 500 | /** |
| 501 | * Stops tracking of heap objects population statistics, cleans up all |
| 502 | * collected data. StartHeapObjectsTracking must be called again prior to |
| 503 | * calling PushHeapObjectsStats next time. |
| 504 | */ |
| 505 | void StopTrackingHeapObjects(); |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 506 | |
| 507 | /** |
| 508 | * Deletes all snapshots taken. All previously returned pointers to |
| 509 | * snapshots and their contents become invalid after this call. |
| 510 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 511 | void DeleteAllHeapSnapshots(); |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 512 | |
| 513 | /** Binds a callback to embedder's class ID. */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 514 | void SetWrapperClassInfoProvider( |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 515 | uint16_t class_id, |
| 516 | WrapperInfoCallback callback); |
| 517 | |
| 518 | /** |
| 519 | * Default value of persistent handle class ID. Must not be used to |
| 520 | * define a class. Can be used to reset a class of a persistent |
| 521 | * handle. |
| 522 | */ |
| 523 | static const uint16_t kPersistentHandleNoClassId = 0; |
Ben Murdoch | 3ef787d | 2012-04-12 10:51:47 +0100 | [diff] [blame] | 524 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 525 | /** Returns memory used for profiler internal data and snapshots. */ |
| 526 | size_t GetProfilerMemorySize(); |
| 527 | |
| 528 | /** |
| 529 | * Sets a RetainedObjectInfo for an object group (see V8::SetObjectGroupId). |
| 530 | */ |
| 531 | void SetRetainedObjectInfo(UniqueId id, RetainedObjectInfo* info); |
| 532 | |
| 533 | private: |
| 534 | HeapProfiler(); |
| 535 | ~HeapProfiler(); |
| 536 | HeapProfiler(const HeapProfiler&); |
| 537 | HeapProfiler& operator=(const HeapProfiler&); |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 538 | }; |
| 539 | |
| 540 | |
| 541 | /** |
| 542 | * Interface for providing information about embedder's objects |
| 543 | * held by global handles. This information is reported in two ways: |
| 544 | * |
| 545 | * 1. When calling AddObjectGroup, an embedder may pass |
| 546 | * RetainedObjectInfo instance describing the group. To collect |
| 547 | * this information while taking a heap snapshot, V8 calls GC |
| 548 | * prologue and epilogue callbacks. |
| 549 | * |
| 550 | * 2. When a heap snapshot is collected, V8 additionally |
| 551 | * requests RetainedObjectInfos for persistent handles that |
| 552 | * were not previously reported via AddObjectGroup. |
| 553 | * |
| 554 | * Thus, if an embedder wants to provide information about native |
| 555 | * objects for heap snapshots, he can do it in a GC prologue |
| 556 | * handler, and / or by assigning wrapper class ids in the following way: |
| 557 | * |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 558 | * 1. Bind a callback to class id by calling SetWrapperClassInfoProvider. |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 559 | * 2. Call SetWrapperClassId on certain persistent handles. |
| 560 | * |
| 561 | * V8 takes ownership of RetainedObjectInfo instances passed to it and |
| 562 | * keeps them alive only during snapshot collection. Afterwards, they |
| 563 | * are freed by calling the Dispose class function. |
| 564 | */ |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 565 | class V8_EXPORT RetainedObjectInfo { // NOLINT |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 566 | public: |
| 567 | /** Called by V8 when it no longer needs an instance. */ |
| 568 | virtual void Dispose() = 0; |
| 569 | |
| 570 | /** Returns whether two instances are equivalent. */ |
| 571 | virtual bool IsEquivalent(RetainedObjectInfo* other) = 0; |
| 572 | |
| 573 | /** |
| 574 | * Returns hash value for the instance. Equivalent instances |
| 575 | * must have the same hash value. |
| 576 | */ |
| 577 | virtual intptr_t GetHash() = 0; |
| 578 | |
| 579 | /** |
Ben Murdoch | 3ef787d | 2012-04-12 10:51:47 +0100 | [diff] [blame] | 580 | * Returns human-readable label. It must be a null-terminated UTF-8 |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 581 | * encoded string. V8 copies its contents during a call to GetLabel. |
| 582 | */ |
| 583 | virtual const char* GetLabel() = 0; |
| 584 | |
| 585 | /** |
Ben Murdoch | 3ef787d | 2012-04-12 10:51:47 +0100 | [diff] [blame] | 586 | * Returns human-readable group label. It must be a null-terminated UTF-8 |
| 587 | * encoded string. V8 copies its contents during a call to GetGroupLabel. |
| 588 | * Heap snapshot generator will collect all the group names, create |
| 589 | * top level entries with these names and attach the objects to the |
| 590 | * corresponding top level group objects. There is a default |
| 591 | * implementation which is required because embedders don't have their |
| 592 | * own implementation yet. |
| 593 | */ |
| 594 | virtual const char* GetGroupLabel() { return GetLabel(); } |
| 595 | |
| 596 | /** |
Steve Block | 44f0eee | 2011-05-26 01:26:41 +0100 | [diff] [blame] | 597 | * Returns element count in case if a global handle retains |
| 598 | * a subgraph by holding one of its nodes. |
| 599 | */ |
| 600 | virtual intptr_t GetElementCount() { return -1; } |
| 601 | |
| 602 | /** Returns embedder's object size in bytes. */ |
| 603 | virtual intptr_t GetSizeInBytes() { return -1; } |
| 604 | |
| 605 | protected: |
| 606 | RetainedObjectInfo() {} |
| 607 | virtual ~RetainedObjectInfo() {} |
| 608 | |
| 609 | private: |
| 610 | RetainedObjectInfo(const RetainedObjectInfo&); |
| 611 | RetainedObjectInfo& operator=(const RetainedObjectInfo&); |
Kristian Monsen | 9dcf7e2 | 2010-06-28 14:14:28 +0100 | [diff] [blame] | 612 | }; |
| 613 | |
| 614 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 615 | /** |
| 616 | * A struct for exporting HeapStats data from V8, using "push" model. |
| 617 | * See HeapProfiler::GetHeapStats. |
| 618 | */ |
| 619 | struct HeapStatsUpdate { |
| 620 | HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size) |
| 621 | : index(index), count(count), size(size) { } |
| 622 | uint32_t index; // Index of the time interval that was changed. |
| 623 | uint32_t count; // New value of count field for the interval with this index. |
| 624 | uint32_t size; // New value of size field for the interval with this index. |
| 625 | }; |
| 626 | |
| 627 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 628 | } // namespace v8 |
| 629 | |
| 630 | |
Steve Block | 6ded16b | 2010-05-10 14:33:55 +0100 | [diff] [blame] | 631 | #endif // V8_V8_PROFILER_H_ |