Line data Source code
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 803229 : class Task {
21 : public:
22 803004 : 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 9156 : class IdleTask {
34 : public:
35 9156 : 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 : */
42 1747 : class ConvertableToTraceFormat {
43 : public:
44 1747 : 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 : */
68 : enum ExpectedRuntime {
69 : kShortRunningTask,
70 : kLongRunningTask
71 : };
72 :
73 58750 : 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 0 : 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 0 : virtual void CallIdleOnForegroundThread(Isolate* isolate, IdleTask* task) {
119 : // TODO(ulan): Make this function abstract after V8 roll in Chromium.
120 0 : }
121 :
122 : /**
123 : * Returns true if idle tasks are enabled for the given |isolate|.
124 : */
125 0 : virtual bool IdleTasksEnabled(Isolate* isolate) {
126 : // TODO(ulan): Make this function abstract after V8 roll in Chromium.
127 0 : 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 0 : virtual const uint8_t* GetCategoryGroupEnabled(const char* name) {
147 : static uint8_t no = 0;
148 0 : 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 0 : virtual const char* GetCategoryGroupName(
156 : const uint8_t* category_enabled_flag) {
157 : static const char dummy[] = "dummy";
158 0 : 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 0 : 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 0 : 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 0 : 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 0 : 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 0 : virtual void UpdateTraceEventDuration(const uint8_t* category_enabled_flag,
201 0 : const char* name, uint64_t handle) {}
202 :
203 59467 : class TraceStateObserver {
204 : public:
205 58750 : virtual ~TraceStateObserver() = default;
206 : virtual void OnTraceEnabled() = 0;
207 : virtual void OnTraceDisabled() = 0;
208 : };
209 :
210 : /** Adds tracing state change observer. */
211 0 : virtual void AddTraceStateObserver(TraceStateObserver*) {}
212 :
213 : /** Removes tracing state change observer. */
214 0 : virtual void RemoveTraceStateObserver(TraceStateObserver*) {}
215 :
216 : typedef void (*StackTracePrinter)();
217 :
218 : /**
219 : * Returns a function pointer that print a stack trace of the current stack
220 : * on invocation. Disables printing of the stack trace if nullptr.
221 : */
222 0 : virtual StackTracePrinter GetStackTracePrinter() { return nullptr; }
223 : };
224 :
225 : } // namespace v8
226 :
227 : #endif // V8_V8_PLATFORM_H_
|
