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