v8  5.5.372 (node 7.10.1)
V8 is Google's open source JavaScript engine
v8-platform.h
Go to the documentation of this file.
1 // Copyright 2013 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_PLATFORM_H_
6 #define V8_V8_PLATFORM_H_
7 
8 #include <stddef.h>
9 #include <stdint.h>
10 #include <memory>
11 #include <string>
12 
13 namespace v8 {
14 
15 class Isolate;
16 
17 /**
18  * A Task represents a unit of work.
19  */
20 class Task {
21  public:
22  virtual ~Task() = default;
23 
24  virtual void Run() = 0;
25 };
26 
27 /**
28  * An IdleTask represents a unit of work to be performed in idle time.
29  * The Run method is invoked with an argument that specifies the deadline in
30  * seconds returned by MonotonicallyIncreasingTime().
31  * The idle task is expected to complete by this deadline.
32  */
33 class IdleTask {
34  public:
35  virtual ~IdleTask() = default;
36  virtual void Run(double deadline_in_seconds) = 0;
37 };
38 
39 /**
40  * The interface represents complex arguments to trace events.
41  */
43  public:
44  virtual ~ConvertableToTraceFormat() = default;
45 
46  /**
47  * Append the class info to the provided |out| string. The appended
48  * data must be a valid JSON object. Strings must be properly quoted, and
49  * escaped. There is no processing applied to the content after it is
50  * appended.
51  */
52  virtual void AppendAsTraceFormat(std::string* out) const = 0;
53 };
54 
55 /**
56  * V8 Platform abstraction layer.
57  *
58  * The embedder has to provide an implementation of this interface before
59  * initializing the rest of V8.
60  */
61 class Platform {
62  public:
63  /**
64  * This enum is used to indicate whether a task is potentially long running,
65  * or causes a long wait. The embedder might want to use this hint to decide
66  * whether to execute the task on a dedicated thread.
67  */
71  };
72 
73  virtual ~Platform() = default;
74 
75  /**
76  * Gets the number of threads that are used to execute background tasks. Is
77  * used to estimate the number of tasks a work package should be split into.
78  * A return value of 0 means that there are no background threads available.
79  * Note that a value of 0 won't prohibit V8 from posting tasks using
80  * |CallOnBackgroundThread|.
81  */
82  virtual size_t NumberOfAvailableBackgroundThreads() { return 0; }
83 
84  /**
85  * Schedules a task to be invoked on a background thread. |expected_runtime|
86  * indicates that the task will run a long time. The Platform implementation
87  * takes ownership of |task|. There is no guarantee about order of execution
88  * of tasks wrt order of scheduling, nor is there a guarantee about the
89  * thread the task will be run on.
90  */
91  virtual void CallOnBackgroundThread(Task* task,
92  ExpectedRuntime expected_runtime) = 0;
93 
94  /**
95  * Schedules a task to be invoked on a foreground thread wrt a specific
96  * |isolate|. Tasks posted for the same isolate should be execute in order of
97  * scheduling. The definition of "foreground" is opaque to V8.
98  */
99  virtual void CallOnForegroundThread(Isolate* isolate, Task* task) = 0;
100 
101  /**
102  * Schedules a task to be invoked on a foreground thread wrt a specific
103  * |isolate| after the given number of seconds |delay_in_seconds|.
104  * Tasks posted for the same isolate should be execute in order of
105  * scheduling. The definition of "foreground" is opaque to V8.
106  */
107  virtual void CallDelayedOnForegroundThread(Isolate* isolate, Task* task,
108  double delay_in_seconds) = 0;
109 
110  /**
111  * Schedules a task to be invoked on a foreground thread wrt a specific
112  * |isolate| when the embedder is idle.
113  * Requires that SupportsIdleTasks(isolate) is true.
114  * Idle tasks may be reordered relative to other task types and may be
115  * starved for an arbitrarily long time if no idle time is available.
116  * The definition of "foreground" is opaque to V8.
117  */
118  virtual void CallIdleOnForegroundThread(Isolate* isolate, IdleTask* task) {
119  // TODO(ulan): Make this function abstract after V8 roll in Chromium.
120  }
121 
122  /**
123  * Returns true if idle tasks are enabled for the given |isolate|.
124  */
125  virtual bool IdleTasksEnabled(Isolate* isolate) {
126  // TODO(ulan): Make this function abstract after V8 roll in Chromium.
127  return false;
128  }
129 
130  /**
131  * Monotonically increasing time in seconds from an arbitrary fixed point in
132  * the past. This function is expected to return at least
133  * millisecond-precision values. For this reason,
134  * it is recommended that the fixed point be no further in the past than
135  * the epoch.
136  **/
137  virtual double MonotonicallyIncreasingTime() = 0;
138 
139  /**
140  * Called by TRACE_EVENT* macros, don't call this directly.
141  * The name parameter is a category group for example:
142  * TRACE_EVENT0("v8,parse", "V8.Parse")
143  * The pointer returned points to a value with zero or more of the bits
144  * defined in CategoryGroupEnabledFlags.
145  **/
146  virtual const uint8_t* GetCategoryGroupEnabled(const char* name) {
147  static uint8_t no = 0;
148  return &no;
149  }
150 
151  /**
152  * Gets the category group name of the given category_enabled_flag pointer.
153  * Usually used while serliazing TRACE_EVENTs.
154  **/
155  virtual const char* GetCategoryGroupName(
156  const uint8_t* category_enabled_flag) {
157  static const char dummy[] = "dummy";
158  return dummy;
159  }
160 
161  /**
162  * Adds a trace event to the platform tracing system. This function call is
163  * usually the result of a TRACE_* macro from trace_event_common.h when
164  * tracing and the category of the particular trace are enabled. It is not
165  * advisable to call this function on its own; it is really only meant to be
166  * used by the trace macros. The returned handle can be used by
167  * UpdateTraceEventDuration to update the duration of COMPLETE events.
168  */
169  virtual uint64_t AddTraceEvent(
170  char phase, const uint8_t* category_enabled_flag, const char* name,
171  const char* scope, uint64_t id, uint64_t bind_id, int32_t num_args,
172  const char** arg_names, const uint8_t* arg_types,
173  const uint64_t* arg_values, unsigned int flags) {
174  return 0;
175  }
176 
177  /**
178  * Adds a trace event to the platform tracing system. This function call is
179  * usually the result of a TRACE_* macro from trace_event_common.h when
180  * tracing and the category of the particular trace are enabled. It is not
181  * advisable to call this function on its own; it is really only meant to be
182  * used by the trace macros. The returned handle can be used by
183  * UpdateTraceEventDuration to update the duration of COMPLETE events.
184  */
185  virtual uint64_t AddTraceEvent(
186  char phase, const uint8_t* category_enabled_flag, const char* name,
187  const char* scope, uint64_t id, uint64_t bind_id, int32_t num_args,
188  const char** arg_names, const uint8_t* arg_types,
189  const uint64_t* arg_values,
190  std::unique_ptr<ConvertableToTraceFormat>* arg_convertables,
191  unsigned int flags) {
192  return AddTraceEvent(phase, category_enabled_flag, name, scope, id, bind_id,
193  num_args, arg_names, arg_types, arg_values, flags);
194  }
195 
196  /**
197  * Sets the duration field of a COMPLETE trace event. It must be called with
198  * the handle returned from AddTraceEvent().
199  **/
200  virtual void UpdateTraceEventDuration(const uint8_t* category_enabled_flag,
201  const char* name, uint64_t handle) {}
202 
204  public:
205  virtual ~TraceStateObserver() = default;
206  virtual void OnTraceEnabled() = 0;
207  virtual void OnTraceDisabled() = 0;
208  };
209 
210  /** Adds tracing state change observer. */
212 
213  /** Removes tracing state change observer. */
215 };
216 
217 } // namespace v8
218 
219 #endif // V8_V8_PLATFORM_H_