v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
platform.h
Go to the documentation of this file.
1 // Copyright 2020 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 INCLUDE_CPPGC_PLATFORM_H_
6 #define INCLUDE_CPPGC_PLATFORM_H_
7 
8 #include <memory>
9 
10 #include "cppgc/source-location.h"
11 #include "v8-platform.h" // NOLINT(build/include_directory)
12 #include "v8config.h" // NOLINT(build/include_directory)
13 
14 namespace cppgc {
15 
16 // TODO(v8:10346): Create separate includes for concepts that are not
17 // V8-specific.
18 using IdleTask = v8::IdleTask;
19 using JobHandle = v8::JobHandle;
20 using JobDelegate = v8::JobDelegate;
21 using JobTask = v8::JobTask;
22 using PageAllocator = v8::PageAllocator;
23 using Task = v8::Task;
24 using TaskPriority = v8::TaskPriority;
25 using TaskRunner = v8::TaskRunner;
26 using TracingController = v8::TracingController;
27 
28 /**
29  * Platform interface used by Heap. Contains allocators and executors.
30  */
32  public:
33  virtual ~Platform() = default;
34 
35  /**
36  * Returns the allocator used by cppgc to allocate its heap and various
37  * support structures.
38  */
39  virtual PageAllocator* GetPageAllocator() = 0;
40 
41  /**
42  * Monotonically increasing time in seconds from an arbitrary fixed point in
43  * the past. This function is expected to return at least
44  * millisecond-precision values. For this reason,
45  * it is recommended that the fixed point be no further in the past than
46  * the epoch.
47  **/
48  virtual double MonotonicallyIncreasingTime() = 0;
49 
50  /**
51  * Foreground task runner that should be used by a Heap.
52  */
53  virtual std::shared_ptr<TaskRunner> GetForegroundTaskRunner() {
54  return nullptr;
55  }
56 
57  /**
58  * Posts `job_task` to run in parallel. Returns a `JobHandle` associated with
59  * the `Job`, which can be joined or canceled.
60  * This avoids degenerate cases:
61  * - Calling `CallOnWorkerThread()` for each work item, causing significant
62  * overhead.
63  * - Fixed number of `CallOnWorkerThread()` calls that split the work and
64  * might run for a long time. This is problematic when many components post
65  * "num cores" tasks and all expect to use all the cores. In these cases,
66  * the scheduler lacks context to be fair to multiple same-priority requests
67  * and/or ability to request lower priority work to yield when high priority
68  * work comes in.
69  * A canonical implementation of `job_task` looks like:
70  * \code
71  * class MyJobTask : public JobTask {
72  * public:
73  * MyJobTask(...) : worker_queue_(...) {}
74  * // JobTask implementation.
75  * void Run(JobDelegate* delegate) override {
76  * while (!delegate->ShouldYield()) {
77  * // Smallest unit of work.
78  * auto work_item = worker_queue_.TakeWorkItem(); // Thread safe.
79  * if (!work_item) return;
80  * ProcessWork(work_item);
81  * }
82  * }
83  *
84  * size_t GetMaxConcurrency() const override {
85  * return worker_queue_.GetSize(); // Thread safe.
86  * }
87  * };
88  *
89  * // ...
90  * auto handle = PostJob(TaskPriority::kUserVisible,
91  * std::make_unique<MyJobTask>(...));
92  * handle->Join();
93  * \endcode
94  *
95  * `PostJob()` and methods of the returned JobHandle/JobDelegate, must never
96  * be called while holding a lock that could be acquired by `JobTask::Run()`
97  * or `JobTask::GetMaxConcurrency()` -- that could result in a deadlock. This
98  * is because (1) `JobTask::GetMaxConcurrency()` may be invoked while holding
99  * internal lock (A), hence `JobTask::GetMaxConcurrency()` can only use a lock
100  * (B) if that lock is *never* held while calling back into `JobHandle` from
101  * any thread (A=>B/B=>A deadlock) and (2) `JobTask::Run()` or
102  * `JobTask::GetMaxConcurrency()` may be invoked synchronously from
103  * `JobHandle` (B=>JobHandle::foo=>B deadlock).
104  *
105  * A sufficient `PostJob()` implementation that uses the default Job provided
106  * in libplatform looks like:
107  * \code
108  * std::unique_ptr<JobHandle> PostJob(
109  * TaskPriority priority, std::unique_ptr<JobTask> job_task) override {
110  * return std::make_unique<DefaultJobHandle>(
111  * std::make_shared<DefaultJobState>(
112  * this, std::move(job_task), kNumThreads));
113  * }
114  * \endcode
115  */
116  virtual std::unique_ptr<JobHandle> PostJob(
117  TaskPriority priority, std::unique_ptr<JobTask> job_task) {
118  return nullptr;
119  }
120 
121  /**
122  * Returns an instance of a `TracingController`. This must be non-nullptr. The
123  * default implementation returns an empty `TracingController` that consumes
124  * trace data without effect.
125  */
126  virtual TracingController* GetTracingController();
127 };
128 
129 /**
130  * Process-global initialization of the garbage collector. Must be called before
131  * creating a Heap.
132  *
133  * Can be called multiple times when paired with `ShutdownProcess()`.
134  *
135  * \param page_allocator The allocator used for maintaining meta data. Must not
136  * change between multiple calls to InitializeProcess.
137  */
138 V8_EXPORT void InitializeProcess(PageAllocator* page_allocator);
139 
140 /**
141  * Must be called after destroying the last used heap. Some process-global
142  * metadata may not be returned and reused upon a subsequent
143  * `InitializeProcess()` call.
144  */
146 
147 namespace internal {
148 
149 V8_EXPORT void Fatal(const std::string& reason = std::string(),
150  const SourceLocation& = SourceLocation::Current());
151 
152 } // namespace internal
153 
154 } // namespace cppgc
155 
156 #endif // INCLUDE_CPPGC_PLATFORM_H_