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 1049689 : class Task {
21 : public:
22 1047932 : 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 5618 : class IdleTask {
34 : public:
35 5618 : 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 1494 : class ConvertableToTraceFormat {
43 : public:
44 1494 : 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 : */
60 54089 : class TracingController {
61 : public:
62 53263 : 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 0 : virtual const uint8_t* GetCategoryGroupEnabled(const char* name) {
72 : static uint8_t no = 0;
73 0 : 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 0 : 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,
89 : std::unique_ptr<ConvertableToTraceFormat>* arg_convertables,
90 : unsigned int flags) {
91 0 : 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 0 : virtual void UpdateTraceEventDuration(const uint8_t* category_enabled_flag,
99 0 : const char* name, uint64_t handle) {}
100 :
101 53982 : class TraceStateObserver {
102 : public:
103 53168 : virtual ~TraceStateObserver() = default;
104 : virtual void OnTraceEnabled() = 0;
105 : virtual void OnTraceDisabled() = 0;
106 : };
107 :
108 : /** Adds tracing state change observer. */
109 0 : virtual void AddTraceStateObserver(TraceStateObserver*) {}
110 :
111 : /** Removes tracing state change observer. */
112 0 : virtual void RemoveTraceStateObserver(TraceStateObserver*) {}
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 54272 : 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 : */
128 : enum ExpectedRuntime {
129 : kShortRunningTask,
130 : kLongRunningTask
131 : };
132 :
133 53381 : 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 0 : 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 : */
151 355 : virtual size_t NumberOfAvailableBackgroundThreads() { return 0; }
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 0 : virtual void CallIdleOnForegroundThread(Isolate* isolate, IdleTask* task) {
188 : // TODO(ulan): Make this function abstract after V8 roll in Chromium.
189 0 : }
190 :
191 : /**
192 : * Returns true if idle tasks are enabled for the given |isolate|.
193 : */
194 0 : virtual bool IdleTasksEnabled(Isolate* isolate) {
195 : // TODO(ulan): Make this function abstract after V8 roll in Chromium.
196 0 : 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() = 0;
213 :
214 : typedef void (*StackTracePrinter)();
215 :
216 : /**
217 : * Returns a function pointer that print a stack trace of the current stack
218 : * on invocation. Disables printing of the stack trace if nullptr.
219 : */
220 0 : virtual StackTracePrinter GetStackTracePrinter() { return nullptr; }
221 :
222 : /**
223 : * Returns an instance of a v8::TracingController. This must be non-nullptr.
224 : */
225 : virtual TracingController* GetTracingController() = 0;
226 :
227 : protected:
228 : /**
229 : * Default implementation of current wall-clock time in milliseconds
230 : * since epoch. Useful for implementing |CurrentClockTimeMillis| if
231 : * nothing special needed.
232 : */
233 : static double SystemClockTimeMillis();
234 : };
235 :
236 : } // namespace v8
237 :
238 : #endif // V8_V8_PLATFORM_H_
|
