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 */ 52 enum ExpectedRuntime { 53 kShortRunningTask, 54 kLongRunningTask 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 */ 66 virtual size_t NumberOfAvailableBackgroundThreads() { return 0; } 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_ 172
