File Explorer

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 be3// 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 14namespace cppgc {15 16// TODO(v8:10346): Create separate includes for concepts that are not17// V8-specific.18using IdleTask = v8::IdleTask;19using JobHandle = v8::JobHandle;20using JobDelegate = v8::JobDelegate;21using JobTask = v8::JobTask;22using PageAllocator = v8::PageAllocator;23using Task = v8::Task;24using TaskPriority = v8::TaskPriority;25using TaskRunner = v8::TaskRunner;26using TracingController = v8::TracingController;27 28/**29 * Platform interface used by Heap. Contains allocators and executors.30 */31class V8_EXPORT Platform {32 public:33  virtual ~Platform() = default;34 35  /**36   * \returns the allocator used by cppgc to allocate its heap and various37   * support structures. Returning nullptr results in using the `PageAllocator`38   * provided by `cppgc::InitializeProcess()` instead.39   */40  virtual PageAllocator* GetPageAllocator() = 0;41 42  /**43   * Monotonically increasing time in seconds from an arbitrary fixed point in44   * the past. This function is expected to return at least45   * millisecond-precision values. For this reason,46   * it is recommended that the fixed point be no further in the past than47   * the epoch.48   **/49  virtual double MonotonicallyIncreasingTime() = 0;50 51  /**52   * Foreground task runner that should be used by a Heap.53   */54  virtual std::shared_ptr<TaskRunner> GetForegroundTaskRunner() {55    return GetForegroundTaskRunner(TaskPriority::kUserBlocking);56  }57 58  /**59   * Returns a TaskRunner with a specific |priority| which can be used to post a60   * task on the foreground thread.61   */62  virtual std::shared_ptr<TaskRunner> GetForegroundTaskRunner(63      TaskPriority priority) {64    return nullptr;65  }66 67  /**68   * Posts `job_task` to run in parallel. Returns a `JobHandle` associated with69   * the `Job`, which can be joined or canceled.70   * This avoids degenerate cases:71   * - Calling `CallOnWorkerThread()` for each work item, causing significant72   *   overhead.73   * - Fixed number of `CallOnWorkerThread()` calls that split the work and74   *   might run for a long time. This is problematic when many components post75   *   "num cores" tasks and all expect to use all the cores. In these cases,76   *   the scheduler lacks context to be fair to multiple same-priority requests77   *   and/or ability to request lower priority work to yield when high priority78   *   work comes in.79   * A canonical implementation of `job_task` looks like:80   * \code81   * class MyJobTask : public JobTask {82   *  public:83   *   MyJobTask(...) : worker_queue_(...) {}84   *   // JobTask implementation.85   *   void Run(JobDelegate* delegate) override {86   *     while (!delegate->ShouldYield()) {87   *       // Smallest unit of work.88   *       auto work_item = worker_queue_.TakeWorkItem(); // Thread safe.89   *       if (!work_item) return;90   *       ProcessWork(work_item);91   *     }92   *   }93   *94   *   size_t GetMaxConcurrency() const override {95   *     return worker_queue_.GetSize(); // Thread safe.96   *   }97   * };98   *99   * // ...100   * auto handle = PostJob(TaskPriority::kUserVisible,101   *                       std::make_unique<MyJobTask>(...));102   * handle->Join();103   * \endcode104   *105   * `PostJob()` and methods of the returned JobHandle/JobDelegate, must never106   * be called while holding a lock that could be acquired by `JobTask::Run()`107   * or `JobTask::GetMaxConcurrency()` -- that could result in a deadlock. This108   * is because (1) `JobTask::GetMaxConcurrency()` may be invoked while holding109   * internal lock (A), hence `JobTask::GetMaxConcurrency()` can only use a lock110   * (B) if that lock is *never* held while calling back into `JobHandle` from111   * any thread (A=>B/B=>A deadlock) and (2) `JobTask::Run()` or112   * `JobTask::GetMaxConcurrency()` may be invoked synchronously from113   * `JobHandle` (B=>JobHandle::foo=>B deadlock).114   *115   * A sufficient `PostJob()` implementation that uses the default Job provided116   * in libplatform looks like:117   * \code118   * std::unique_ptr<JobHandle> PostJob(119   *     TaskPriority priority, std::unique_ptr<JobTask> job_task) override {120   *   return std::make_unique<DefaultJobHandle>(121   *       std::make_shared<DefaultJobState>(122   *           this, std::move(job_task), kNumThreads));123   * }124   * \endcode125   */126  virtual std::unique_ptr<JobHandle> PostJob(127      TaskPriority priority, std::unique_ptr<JobTask> job_task) {128    return nullptr;129  }130 131  /**132   * Returns an instance of a `TracingController`. This must be non-nullptr. The133   * default implementation returns an empty `TracingController` that consumes134   * trace data without effect.135   */136  virtual TracingController* GetTracingController();137};138 139V8_EXPORT bool IsInitialized();140 141/**142 * Process-global initialization of the garbage collector. Must be called before143 * creating a Heap.144 *145 * Can be called multiple times when paired with `ShutdownProcess()`.146 *147 * \param page_allocator The allocator used for maintaining meta data. Must stay148 *   always alive and not change between multiple calls to InitializeProcess. If149 *   no allocator is provided, a default internal version will be used.150 * \param desired_heap_size Desired amount of virtual address space to reserve151 *   for the heap, in bytes. Actual size will be clamped to minimum and maximum152 *   values based on compile-time settings and may be rounded up. If this153 *   parameter is zero, a default value will be used.154 */155V8_EXPORT void InitializeProcess(PageAllocator* page_allocator = nullptr,156                                 size_t desired_heap_size = 0);157 158/**159 * Must be called after destroying the last used heap. Some process-global160 * metadata may not be returned and reused upon a subsequent161 * `InitializeProcess()` call.162 */163V8_EXPORT void ShutdownProcess();164 165namespace internal {166 167V8_EXPORT void Fatal(const std::string& reason = std::string(),168                     const SourceLocation& = SourceLocation::Current());169 170}  // namespace internal171 172}  // namespace cppgc173 174#endif  // INCLUDE_CPPGC_PLATFORM_H_175