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 */ 42 class ConvertableToTraceFormat { 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 */ 68 enum ExpectedRuntime { 69 kShortRunningTask, 70 kLongRunningTask 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 203 class TraceStateObserver { 204 public: 205 virtual ~TraceStateObserver() = default; 206 virtual void OnTraceEnabled() = 0; 207 virtual void OnTraceDisabled() = 0; 208 }; 209 210 /** Adds tracing state change observer. */ 211 virtual void AddTraceStateObserver(TraceStateObserver*) {} 212 213 /** Removes tracing state change observer. */ 214 virtual void RemoveTraceStateObserver(TraceStateObserver*) {} 215 }; 216 217 } // namespace v8 218 219 #endif // V8_V8_PLATFORM_H_ 220
