platform.h 5.37 KB
Newer Older
1 2 3 4 5 6 7
// Copyright 2020 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef INCLUDE_CPPGC_PLATFORM_H_
#define INCLUDE_CPPGC_PLATFORM_H_

8 9
#include <memory>

10
#include "cppgc/source-location.h"
11 12
#include "v8-platform.h"  // NOLINT(build/include_directory)
#include "v8config.h"     // NOLINT(build/include_directory)
13 14 15

namespace cppgc {

16 17
// TODO(v8:10346): Create separate includes for concepts that are not
// 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 25
using TaskPriority = v8::TaskPriority;
using TaskRunner = v8::TaskRunner;
Omer Katz's avatar
Omer Katz committed
26
using TracingController = v8::TracingController;
27

28 29 30 31 32 33
/**
 * Platform interface used by Heap. Contains allocators and executors.
 */
class V8_EXPORT Platform {
 public:
  virtual ~Platform() = default;
34

35 36 37 38 39
  /**
   * Returns the allocator used by cppgc to allocate its heap and various
   * support structures.
   */
  virtual PageAllocator* GetPageAllocator() = 0;
40

41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
  /**
   * Monotonically increasing time in seconds from an arbitrary fixed point in
   * the past. This function is expected to return at least
   * millisecond-precision values. For this reason,
   * it is recommended that the fixed point be no further in the past than
   * the epoch.
   **/
  virtual double MonotonicallyIncreasingTime() = 0;

  /**
   * Foreground task runner that should be used by a Heap.
   */
  virtual std::shared_ptr<TaskRunner> GetForegroundTaskRunner() {
    return nullptr;
  }

  /**
58 59
   * Posts `job_task` to run in parallel. Returns a `JobHandle` associated with
   * 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 64
   * - Fixed number of `CallOnWorkerThread()` calls that split the work and
   *   might run for a long time. This is problematic when many components post
65 66 67 68
   *   "num cores" tasks and all expect to use all the cores. In these cases,
   *   the scheduler lacks context to be fair to multiple same-priority requests
   *   and/or ability to request lower priority work to yield when high priority
   *   work comes in.
69 70
   * A canonical implementation of `job_task` looks like:
   * \code
71 72 73
   * class MyJobTask : public JobTask {
   *  public:
   *   MyJobTask(...) : worker_queue_(...) {}
74
   *   // JobTask implementation.
75 76 77 78 79 80 81 82 83 84 85 86 87
   *   void Run(JobDelegate* delegate) override {
   *     while (!delegate->ShouldYield()) {
   *       // Smallest unit of work.
   *       auto work_item = worker_queue_.TakeWorkItem(); // Thread safe.
   *       if (!work_item) return;
   *       ProcessWork(work_item);
   *     }
   *   }
   *
   *   size_t GetMaxConcurrency() const override {
   *     return worker_queue_.GetSize(); // Thread safe.
   *   }
   * };
88 89
   *
   * // ...
90 91 92
   * auto handle = PostJob(TaskPriority::kUserVisible,
   *                       std::make_unique<MyJobTask>(...));
   * handle->Join();
93
   * \endcode
94
   *
95 96 97 98 99 100 101 102 103
   * `PostJob()` and methods of the returned JobHandle/JobDelegate, must never
   * be called while holding a lock that could be acquired by `JobTask::Run()`
   * or `JobTask::GetMaxConcurrency()` -- that could result in a deadlock. This
   * is because (1) `JobTask::GetMaxConcurrency()` may be invoked while holding
   * internal lock (A), hence `JobTask::GetMaxConcurrency()` can only use a lock
   * (B) if that lock is *never* held while calling back into `JobHandle` from
   * any thread (A=>B/B=>A deadlock) and (2) `JobTask::Run()` or
   * `JobTask::GetMaxConcurrency()` may be invoked synchronously from
   * `JobHandle` (B=>JobHandle::foo=>B deadlock).
104
   *
105 106 107 108 109 110 111 112
   * A sufficient `PostJob()` implementation that uses the default Job provided
   * in libplatform looks like:
   * \code
   * std::unique_ptr<JobHandle> PostJob(
   *     TaskPriority priority, std::unique_ptr<JobTask> job_task) override {
   *   return std::make_unique<DefaultJobHandle>(
   *       std::make_shared<DefaultJobState>(
   *           this, std::move(job_task), kNumThreads));
113
   * }
114
   * \endcode
115 116 117 118 119
   */
  virtual std::unique_ptr<JobHandle> PostJob(
      TaskPriority priority, std::unique_ptr<JobTask> job_task) {
    return nullptr;
  }
Omer Katz's avatar
Omer Katz committed
120 121

  /**
122 123 124
   * Returns an instance of a `TracingController`. This must be non-nullptr. The
   * default implementation returns an empty `TracingController` that consumes
   * trace data without effect.
Omer Katz's avatar
Omer Katz committed
125
   */
126
  virtual TracingController* GetTracingController();
127 128 129 130
};

/**
 * Process-global initialization of the garbage collector. Must be called before
131 132 133 134
 * creating a Heap.
 *
 * Can be called multiple times when paired with `ShutdownProcess()`.
 *
135 136
 * \param page_allocator The allocator used for maintaining meta data. Must stay
 *   always alive and not change between multiple calls to InitializeProcess.
137
 */
138
V8_EXPORT void InitializeProcess(PageAllocator* page_allocator);
139 140

/**
141 142 143
 * Must be called after destroying the last used heap. Some process-global
 * metadata may not be returned and reused upon a subsequent
 * `InitializeProcess()` call.
144 145
 */
V8_EXPORT void ShutdownProcess();
146 147 148

namespace internal {

149 150
V8_EXPORT void Fatal(const std::string& reason = std::string(),
                     const SourceLocation& = SourceLocation::Current());
151 152

}  // namespace internal
153

154 155 156
}  // namespace cppgc

#endif  // INCLUDE_CPPGC_PLATFORM_H_