Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | 097c5b2 | 2016-05-18 11:27:45 +0100 | [diff] [blame] | 8 | #include <stddef.h> |
Ben Murdoch | 4a90d5f | 2016-03-22 12:00:34 +0000 | [diff] [blame] | 9 | #include <stdint.h> |
| 10 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | 4a90d5f | 2016-03-22 12:00:34 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 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 | /** |
Ben Murdoch | 097c5b2 | 2016-05-18 11:27:45 +0100 | [diff] [blame] | 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 | /** |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 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; |
Emily Bernier | d0a1eb7 | 2015-03-24 16:35:39 -0400 | [diff] [blame] | 84 | |
| 85 | /** |
Ben Murdoch | 4a90d5f | 2016-03-22 12:00:34 +0000 | [diff] [blame] | 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 | /** |
Emily Bernier | d0a1eb7 | 2015-03-24 16:35:39 -0400 | [diff] [blame] | 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; |
Ben Murdoch | 4a90d5f | 2016-03-22 12:00:34 +0000 | [diff] [blame] | 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, |
Ben Murdoch | da12d29 | 2016-06-02 14:46:10 +0100 | [diff] [blame] | 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) { |
Ben Murdoch | 4a90d5f | 2016-03-22 12:00:34 +0000 | [diff] [blame] | 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) {} |
Ben Murdoch | b8a8cc1 | 2014-11-26 15:28:44 +0000 | [diff] [blame] | 167 | }; |
| 168 | |
| 169 | } // namespace v8 |
| 170 | |
| 171 | #endif // V8_V8_PLATFORM_H_ |