v8  6.2.414(node9.11.2)
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 Tracing controller.
57  *
58  * Can be implemented by an embedder to record trace events from V8.
59  */
61  public:
62  virtual ~TracingController() = default;
63 
64  /**
65  * Called by TRACE_EVENT* macros, don't call this directly.
66  * The name parameter is a category group for example:
67  * TRACE_EVENT0("v8,parse", "V8.Parse")
68  * The pointer returned points to a value with zero or more of the bits
69  * defined in CategoryGroupEnabledFlags.
70  **/
71  virtual const uint8_t* GetCategoryGroupEnabled(const char* name) {
72  static uint8_t no = 0;
73  return &no;
74  }
75 
76  /**
77  * Adds a trace event to the platform tracing system. This function call is
78  * usually the result of a TRACE_* macro from trace_event_common.h when
79  * tracing and the category of the particular trace are enabled. It is not
80  * advisable to call this function on its own; it is really only meant to be
81  * used by the trace macros. The returned handle can be used by
82  * UpdateTraceEventDuration to update the duration of COMPLETE events.
83  */
84  virtual uint64_t AddTraceEvent(
85  char phase, const uint8_t* category_enabled_flag, const char* name,
86  const char* scope, uint64_t id, uint64_t bind_id, int32_t num_args,
87  const char** arg_names, const uint8_t* arg_types,
88  const uint64_t* arg_values,
90  unsigned int flags) {
91  return 0;
92  }
93 
94  /**
95  * Sets the duration field of a COMPLETE trace event. It must be called with
96  * the handle returned from AddTraceEvent().
97  **/
98  virtual void UpdateTraceEventDuration(const uint8_t* category_enabled_flag,
99  const char* name, uint64_t handle) {}
100 
102  public:
103  virtual ~TraceStateObserver() = default;
104  virtual void OnTraceEnabled() = 0;
105  virtual void OnTraceDisabled() = 0;
106  };
107 
108  /** Adds tracing state change observer. */
110 
111  /** Removes tracing state change observer. */
113 };
114 
115 /**
116  * V8 Platform abstraction layer.
117  *
118  * The embedder has to provide an implementation of this interface before
119  * initializing the rest of V8.
120  */
121 class Platform {
122  public:
123  /**
124  * This enum is used to indicate whether a task is potentially long running,
125  * or causes a long wait. The embedder might want to use this hint to decide
126  * whether to execute the task on a dedicated thread.
127  */
131  };
132 
133  virtual ~Platform() = default;
134 
135  /**
136  * Enables the embedder to respond in cases where V8 can't allocate large
137  * blocks of memory. V8 retries the failed allocation once after calling this
138  * method. On success, execution continues; otherwise V8 exits with a fatal
139  * error.
140  * Embedder overrides of this function must NOT call back into V8.
141  */
142  virtual void OnCriticalMemoryPressure() {}
143 
144  /**
145  * Gets the number of threads that are used to execute background tasks. Is
146  * used to estimate the number of tasks a work package should be split into.
147  * A return value of 0 means that there are no background threads available.
148  * Note that a value of 0 won't prohibit V8 from posting tasks using
149  * |CallOnBackgroundThread|.
150  */
152 
153  /**
154  * Schedules a task to be invoked on a background thread. |expected_runtime|
155  * indicates that the task will run a long time. The Platform implementation
156  * takes ownership of |task|. There is no guarantee about order of execution
157  * of tasks wrt order of scheduling, nor is there a guarantee about the
158  * thread the task will be run on.
159  */
160  virtual void CallOnBackgroundThread(Task* task,
161  ExpectedRuntime expected_runtime) = 0;
162 
163  /**
164  * Schedules a task to be invoked on a foreground thread wrt a specific
165  * |isolate|. Tasks posted for the same isolate should be execute in order of
166  * scheduling. The definition of "foreground" is opaque to V8.
167  */
168  virtual void CallOnForegroundThread(Isolate* isolate, Task* task) = 0;
169 
170  /**
171  * Schedules a task to be invoked on a foreground thread wrt a specific
172  * |isolate| after the given number of seconds |delay_in_seconds|.
173  * Tasks posted for the same isolate should be execute in order of
174  * scheduling. The definition of "foreground" is opaque to V8.
175  */
176  virtual void CallDelayedOnForegroundThread(Isolate* isolate, Task* task,
177  double delay_in_seconds) = 0;
178 
179  /**
180  * Schedules a task to be invoked on a foreground thread wrt a specific
181  * |isolate| when the embedder is idle.
182  * Requires that SupportsIdleTasks(isolate) is true.
183  * Idle tasks may be reordered relative to other task types and may be
184  * starved for an arbitrarily long time if no idle time is available.
185  * The definition of "foreground" is opaque to V8.
186  */
187  virtual void CallIdleOnForegroundThread(Isolate* isolate, IdleTask* task) {
188  // TODO(ulan): Make this function abstract after V8 roll in Chromium.
189  }
190 
191  /**
192  * Returns true if idle tasks are enabled for the given |isolate|.
193  */
194  virtual bool IdleTasksEnabled(Isolate* isolate) {
195  // TODO(ulan): Make this function abstract after V8 roll in Chromium.
196  return false;
197  }
198 
199  /**
200  * Monotonically increasing time in seconds from an arbitrary fixed point in
201  * the past. This function is expected to return at least
202  * millisecond-precision values. For this reason,
203  * it is recommended that the fixed point be no further in the past than
204  * the epoch.
205  **/
206  virtual double MonotonicallyIncreasingTime() = 0;
207 
208  /**
209  * Current wall-clock time in milliseconds since epoch.
210  * This function is expected to return at least millisecond-precision values.
211  */
212  virtual double CurrentClockTimeMillis() {
213  // TODO(dats): Make pure virtual after V8 roll in Chromium.
214  return 0.0;
215  }
216 
217  typedef void (*StackTracePrinter)();
218 
219  /**
220  * Returns a function pointer that print a stack trace of the current stack
221  * on invocation. Disables printing of the stack trace if nullptr.
222  */
223  virtual StackTracePrinter GetStackTracePrinter() { return nullptr; }
224 
225  /**
226  * Returns an instance of a v8::TracingController. This must be non-nullptr.
227  */
229 
230  protected:
231  /**
232  * Default implementation of current wall-clock time in milliseconds
233  * since epoch. Useful for implementing |CurrentClockTimeMillis| if
234  * nothing special needed.
235  */
236  static double SystemClockTimeMillis();
237 };
238 
239 } // namespace v8
240 
241 #endif // V8_V8_PLATFORM_H_
virtual void RemoveTraceStateObserver(TraceStateObserver *)
Definition: v8-platform.h:112
virtual ~Platform()=default
virtual StackTracePrinter GetStackTracePrinter()
Definition: v8-platform.h:223
virtual void Run()=0
size_t(* GetExternallyAllocatedMemoryInBytesCallback)()
Definition: v8.h:7299
virtual void CallOnBackgroundThread(Task *task, ExpectedRuntime expected_runtime)=0
virtual const uint8_t * GetCategoryGroupEnabled(const char *name)
Definition: v8-platform.h:71
virtual uint64_t AddTraceEvent(char phase, const uint8_t *category_enabled_flag, const char *name, const char *scope, uint64_t id, uint64_t bind_id, int32_t num_args, const char **arg_names, const uint8_t *arg_types, const uint64_t *arg_values, std::unique_ptr< ConvertableToTraceFormat > *arg_convertables, unsigned int flags)
Definition: v8-platform.h:84
virtual void AddTraceStateObserver(TraceStateObserver *)
Definition: v8-platform.h:109
virtual void AppendAsTraceFormat(std::string *out) const =0
void(* StackTracePrinter)()
Definition: v8-platform.h:217
virtual double CurrentClockTimeMillis()
Definition: v8-platform.h:212
virtual ~TracingController()=default
virtual ~Task()=default
virtual ~ConvertableToTraceFormat()=default
virtual bool IdleTasksEnabled(Isolate *isolate)
Definition: v8-platform.h:194
virtual double MonotonicallyIncreasingTime()=0
static double SystemClockTimeMillis()
constexpr uint32_t CurrentValueSerializerFormatVersion()
virtual ~IdleTask()=default
virtual void OnCriticalMemoryPressure()
Definition: v8-platform.h:142
virtual void UpdateTraceEventDuration(const uint8_t *category_enabled_flag, const char *name, uint64_t handle)
Definition: v8-platform.h:98
virtual size_t NumberOfAvailableBackgroundThreads()
Definition: v8-platform.h:151
virtual void CallIdleOnForegroundThread(Isolate *isolate, IdleTask *task)
Definition: v8-platform.h:187
virtual void Run(double deadline_in_seconds)=0
virtual TracingController * GetTracingController()=0
virtual void CallOnForegroundThread(Isolate *isolate, Task *task)=0
virtual void CallDelayedOnForegroundThread(Isolate *isolate, Task *task, double delay_in_seconds)=0