v8  5.1.281(node6.10.3)
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 
11 namespace v8 {
12 
13 class Isolate;
14 
15 /**
16  * A Task represents a unit of work.
17  */
18 class Task {
19  public:
20  virtual ~Task() {}
21 
22  virtual void Run() = 0;
23 };
24 
25 
26 /**
27 * An IdleTask represents a unit of work to be performed in idle time.
28 * The Run method is invoked with an argument that specifies the deadline in
29 * seconds returned by MonotonicallyIncreasingTime().
30 * The idle task is expected to complete by this deadline.
31 */
32 class IdleTask {
33  public:
34  virtual ~IdleTask() {}
35  virtual void Run(double deadline_in_seconds) = 0;
36 };
37 
38 
39 /**
40  * V8 Platform abstraction layer.
41  *
42  * The embedder has to provide an implementation of this interface before
43  * initializing the rest of V8.
44  */
45 class Platform {
46  public:
47  /**
48  * This enum is used to indicate whether a task is potentially long running,
49  * or causes a long wait. The embedder might want to use this hint to decide
50  * whether to execute the task on a dedicated thread.
51  */
55  };
56 
57  virtual ~Platform() {}
58 
59  /**
60  * Gets the number of threads that are used to execute background tasks. Is
61  * used to estimate the number of tasks a work package should be split into.
62  * A return value of 0 means that there are no background threads available.
63  * Note that a value of 0 won't prohibit V8 from posting tasks using
64  * |CallOnBackgroundThread|.
65  */
67 
68  /**
69  * Schedules a task to be invoked on a background thread. |expected_runtime|
70  * indicates that the task will run a long time. The Platform implementation
71  * takes ownership of |task|. There is no guarantee about order of execution
72  * of tasks wrt order of scheduling, nor is there a guarantee about the
73  * thread the task will be run on.
74  */
75  virtual void CallOnBackgroundThread(Task* task,
76  ExpectedRuntime expected_runtime) = 0;
77 
78  /**
79  * Schedules a task to be invoked on a foreground thread wrt a specific
80  * |isolate|. Tasks posted for the same isolate should be execute in order of
81  * scheduling. The definition of "foreground" is opaque to V8.
82  */
83  virtual void CallOnForegroundThread(Isolate* isolate, Task* task) = 0;
84 
85  /**
86  * Schedules a task to be invoked on a foreground thread wrt a specific
87  * |isolate| after the given number of seconds |delay_in_seconds|.
88  * Tasks posted for the same isolate should be execute in order of
89  * scheduling. The definition of "foreground" is opaque to V8.
90  */
91  virtual void CallDelayedOnForegroundThread(Isolate* isolate, Task* task,
92  double delay_in_seconds) = 0;
93 
94  /**
95  * Schedules a task to be invoked on a foreground thread wrt a specific
96  * |isolate| when the embedder is idle.
97  * Requires that SupportsIdleTasks(isolate) is true.
98  * Idle tasks may be reordered relative to other task types and may be
99  * starved for an arbitrarily long time if no idle time is available.
100  * The definition of "foreground" is opaque to V8.
101  */
102  virtual void CallIdleOnForegroundThread(Isolate* isolate, IdleTask* task) {
103  // TODO(ulan): Make this function abstract after V8 roll in Chromium.
104  }
105 
106  /**
107  * Returns true if idle tasks are enabled for the given |isolate|.
108  */
109  virtual bool IdleTasksEnabled(Isolate* isolate) {
110  // TODO(ulan): Make this function abstract after V8 roll in Chromium.
111  return false;
112  }
113 
114  /**
115  * Monotonically increasing time in seconds from an arbitrary fixed point in
116  * the past. This function is expected to return at least
117  * millisecond-precision values. For this reason,
118  * it is recommended that the fixed point be no further in the past than
119  * the epoch.
120  **/
121  virtual double MonotonicallyIncreasingTime() = 0;
122 
123  /**
124  * Called by TRACE_EVENT* macros, don't call this directly.
125  * The name parameter is a category group for example:
126  * TRACE_EVENT0("v8,parse", "V8.Parse")
127  * The pointer returned points to a value with zero or more of the bits
128  * defined in CategoryGroupEnabledFlags.
129  **/
130  virtual const uint8_t* GetCategoryGroupEnabled(const char* name) {
131  static uint8_t no = 0;
132  return &no;
133  }
134 
135  /**
136  * Gets the category group name of the given category_enabled_flag pointer.
137  * Usually used while serliazing TRACE_EVENTs.
138  **/
139  virtual const char* GetCategoryGroupName(
140  const uint8_t* category_enabled_flag) {
141  static const char dummy[] = "dummy";
142  return dummy;
143  }
144 
145  /**
146  * Adds a trace event to the platform tracing system. This function call is
147  * usually the result of a TRACE_* macro from trace_event_common.h when
148  * tracing and the category of the particular trace are enabled. It is not
149  * advisable to call this function on its own; it is really only meant to be
150  * used by the trace macros. The returned handle can be used by
151  * UpdateTraceEventDuration to update the duration of COMPLETE events.
152  */
153  virtual uint64_t AddTraceEvent(
154  char phase, const uint8_t* category_enabled_flag, const char* name,
155  const char* scope, uint64_t id, uint64_t bind_id, int32_t num_args,
156  const char** arg_names, const uint8_t* arg_types,
157  const uint64_t* arg_values, unsigned int flags) {
158  return 0;
159  }
160 
161  /**
162  * Sets the duration field of a COMPLETE trace event. It must be called with
163  * the handle returned from AddTraceEvent().
164  **/
165  virtual void UpdateTraceEventDuration(const uint8_t* category_enabled_flag,
166  const char* name, uint64_t handle) {}
167 };
168 
169 } // namespace v8
170 
171 #endif // V8_V8_PLATFORM_H_
virtual const uint8_t * GetCategoryGroupEnabled(const char *name)
Definition: v8-platform.h:130
virtual void Run()=0
virtual const char * GetCategoryGroupName(const uint8_t *category_enabled_flag)
Definition: v8-platform.h:139
virtual ~Task()
Definition: v8-platform.h:20
virtual ~Platform()
Definition: v8-platform.h:57
virtual void CallOnBackgroundThread(Task *task, ExpectedRuntime expected_runtime)=0
Definition: libplatform.h:10
virtual bool IdleTasksEnabled(Isolate *isolate)
Definition: v8-platform.h:109
virtual double MonotonicallyIncreasingTime()=0
virtual size_t NumberOfAvailableBackgroundThreads()
Definition: v8-platform.h:66
virtual void CallIdleOnForegroundThread(Isolate *isolate, IdleTask *task)
Definition: v8-platform.h:102
virtual void Run(double deadline_in_seconds)=0
virtual void UpdateTraceEventDuration(const uint8_t *category_enabled_flag, const char *name, uint64_t handle)
Definition: v8-platform.h:165
virtual void CallOnForegroundThread(Isolate *isolate, Task *task)=0
virtual void CallDelayedOnForegroundThread(Isolate *isolate, Task *task, double delay_in_seconds)=0
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, unsigned int flags)
Definition: v8-platform.h:153
virtual ~IdleTask()
Definition: v8-platform.h:34