v8-profiler.h revision 6ded16be15dd865a9b21ea304d5273c8be299c87 
1// Copyright 2010 the V8 project authors. All rights reserved.
2// Redistribution and use in source and binary forms, with or without
3// modification, are permitted provided that the following conditions are
4// met:
5//
6//     * Redistributions of source code must retain the above copyright
7//       notice, this list of conditions and the following disclaimer.
8//     * Redistributions in binary form must reproduce the above
9//       copyright notice, this list of conditions and the following
10//       disclaimer in the documentation and/or other materials provided
11//       with the distribution.
12//     * Neither the name of Google Inc. nor the names of its
13//       contributors may be used to endorse or promote products derived
14//       from this software without specific prior written permission.
15//
16// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27
28#ifndef V8_V8_PROFILER_H_
29#define V8_V8_PROFILER_H_
30
31#include "v8.h"
32
33#ifdef _WIN32
34// Setup for Windows DLL export/import. See v8.h in this directory for
35// information on how to build/use V8 as a DLL.
36#if defined(BUILDING_V8_SHARED) && defined(USING_V8_SHARED)
37#error both BUILDING_V8_SHARED and USING_V8_SHARED are set - please check the\
38  build configuration to ensure that at most one of these is set
39#endif
40
41#ifdef BUILDING_V8_SHARED
42#define V8EXPORT __declspec(dllexport)
43#elif USING_V8_SHARED
44#define V8EXPORT __declspec(dllimport)
45#else
46#define V8EXPORT
47#endif
48
49#else  // _WIN32
50
51// Setup for Linux shared library export. See v8.h in this directory for
52// information on how to build/use V8 as shared library.
53#if defined(__GNUC__) && (__GNUC__ >= 4) && defined(V8_SHARED)
54#define V8EXPORT __attribute__ ((visibility("default")))
55#else  // defined(__GNUC__) && (__GNUC__ >= 4)
56#define V8EXPORT
57#endif  // defined(__GNUC__) && (__GNUC__ >= 4)
58
59#endif  // _WIN32
60
61
62/**
63 * Profiler support for the V8 JavaScript engine.
64 */
65namespace v8 {
66
67
68/**
69 * CpuProfileNode represents a node in a call graph.
70 */
71class V8EXPORT CpuProfileNode {
72 public:
73  /** Returns function name (empty string for anonymous functions.) */
74  Handle<String> GetFunctionName() const;
75
76  /** Returns resource name for script from where the function originates. */
77  Handle<String> GetScriptResourceName() const;
78
79  /**
80   * Returns the number, 1-based, of the line where the function originates.
81   * kNoLineNumberInfo if no line number information is available.
82   */
83  int GetLineNumber() const;
84
85  /**
86   * Returns total (self + children) execution time of the function,
87   * in milliseconds, estimated by samples count.
88   */
89  double GetTotalTime() const;
90
91  /**
92   * Returns self execution time of the function, in milliseconds,
93   * estimated by samples count.
94   */
95  double GetSelfTime() const;
96
97  /** Returns the count of samples where function exists. */
98  double GetTotalSamplesCount() const;
99
100  /** Returns the count of samples where function was currently executing. */
101  double GetSelfSamplesCount() const;
102
103  /** Returns function entry UID. */
104  unsigned GetCallUid() const;
105
106  /** Returns child nodes count of the node. */
107  int GetChildrenCount() const;
108
109  /** Retrieves a child node by index. */
110  const CpuProfileNode* GetChild(int index) const;
111
112  static const int kNoLineNumberInfo = 0;
113};
114
115
116/**
117 * CpuProfile contains a CPU profile in a form of two call trees:
118 *  - top-down (from main() down to functions that do all the work);
119 *  - bottom-up call graph (in backward direction).
120 */
121class V8EXPORT CpuProfile {
122 public:
123  /** Returns CPU profile UID (assigned by the profiler.) */
124  unsigned GetUid() const;
125
126  /** Returns CPU profile title. */
127  Handle<String> GetTitle() const;
128
129  /** Returns the root node of the bottom up call tree. */
130  const CpuProfileNode* GetBottomUpRoot() const;
131
132  /** Returns the root node of the top down call tree. */
133  const CpuProfileNode* GetTopDownRoot() const;
134};
135
136
137/**
138 * Interface for controlling CPU profiling.
139 */
140class V8EXPORT CpuProfiler {
141 public:
142  /**
143   * Returns the number of profiles collected (doesn't include
144   * profiles that are being collected at the moment of call.)
145   */
146  static int GetProfilesCount();
147
148  /** Returns a profile by index. */
149  static const CpuProfile* GetProfile(int index);
150
151  /** Returns a profile by uid. */
152  static const CpuProfile* FindProfile(unsigned uid);
153
154  /**
155   * Starts collecting CPU profile. Title may be an empty string. It
156   * is allowed to have several profiles being collected at
157   * once. Attempts to start collecting several profiles with the same
158   * title are silently ignored.
159   */
160  static void StartProfiling(Handle<String> title);
161
162  /**
163   * Stops collecting CPU profile with a given title and returns it.
164   * If the title given is empty, finishes the last profile started.
165   */
166  static const CpuProfile* StopProfiling(Handle<String> title);
167};
168
169
170}  // namespace v8
171
172
173#undef V8EXPORT
174
175
176#endif  // V8_V8_PROFILER_H_
177