include/node/v8-cppgc.h

0001 // Copyright 2020 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_V8_CPPGC_H_
0006 #define INCLUDE_V8_CPPGC_H_
0007
0008 #include <cstdint>
0009 #include <memory>
0010 #include <vector>
0011
0012 #include "cppgc/common.h"
0013 #include "cppgc/custom-space.h"
0014 #include "cppgc/heap-statistics.h"
0015 #include "cppgc/visitor.h"
0016 #include "v8-internal.h"       // NOLINT(build/include_directory)
0017 #include "v8-platform.h"       // NOLINT(build/include_directory)
0018 #include "v8-traced-handle.h"  // NOLINT(build/include_directory)
0019
0020 namespace cppgc {
0021 class AllocationHandle;
0022 class HeapHandle;
0023 }  // namespace cppgc
0024
0025 namespace v8 {
0026
0027 class Object;
0028
0029 namespace internal {
0030 class CppHeap;
0031 }  // namespace internal
0032
0033 class CustomSpaceStatisticsReceiver;
0034
0035 struct V8_EXPORT CppHeapCreateParams {
0036   explicit CppHeapCreateParams(
0037       std::vector<std::unique_ptr<cppgc::CustomSpaceBase>> custom_spaces)
0038       : custom_spaces(std::move(custom_spaces)) {}
0039
0040   CppHeapCreateParams(const CppHeapCreateParams&) = delete;
0041   CppHeapCreateParams& operator=(const CppHeapCreateParams&) = delete;
0042
0043   std::vector<std::unique_ptr<cppgc::CustomSpaceBase>> custom_spaces;
0044   /**
0045    * Specifies which kind of marking are supported by the heap. The type may be
0046    * further reduced via runtime flags when attaching the heap to an Isolate.
0047    */
0048   cppgc::Heap::MarkingType marking_support =
0049       cppgc::Heap::MarkingType::kIncrementalAndConcurrent;
0050   /**
0051    * Specifies which kind of sweeping is supported by the heap. The type may be
0052    * further reduced via runtime flags when attaching the heap to an Isolate.
0053    */
0054   cppgc::Heap::SweepingType sweeping_support =
0055       cppgc::Heap::SweepingType::kIncrementalAndConcurrent;
0056 };
0057
0058 /**
0059  * A heap for allocating managed C++ objects.
0060  *
0061  * Similar to v8::Isolate, the heap may only be accessed from one thread at a
0062  * time. The heap may be used from different threads using the
0063  * v8::Locker/v8::Unlocker APIs which is different from generic Oilpan.
0064  */
0065 class V8_EXPORT CppHeap {
0066  public:
0067   static std::unique_ptr<CppHeap> Create(v8::Platform* platform,
0068                                          const CppHeapCreateParams& params);
0069
0070   virtual ~CppHeap() = default;
0071
0072   /**
0073    * \returns the opaque handle for allocating objects using
0074    * `MakeGarbageCollected()`.
0075    */
0076   cppgc::AllocationHandle& GetAllocationHandle();
0077
0078   /**
0079    * \returns the opaque heap handle which may be used to refer to this heap in
0080    *   other APIs. Valid as long as the underlying `CppHeap` is alive.
0081    */
0082   cppgc::HeapHandle& GetHeapHandle();
0083
0084   /**
0085    * Terminate clears all roots and performs multiple garbage collections to
0086    * reclaim potentially newly created objects in destructors.
0087    *
0088    * After this call, object allocation is prohibited.
0089    */
0090   V8_DEPRECATED("Terminate gets automatically called in the CppHeap destructor")
0091   void Terminate();
0092
0093   /**
0094    * \param detail_level specifies whether should return detailed
0095    *   statistics or only brief summary statistics.
0096    * \returns current CppHeap statistics regarding memory consumption
0097    *   and utilization.
0098    */
0099   cppgc::HeapStatistics CollectStatistics(
0100       cppgc::HeapStatistics::DetailLevel detail_level);
0101
0102   /**
0103    * Collects statistics for the given spaces and reports them to the receiver.
0104    *
0105    * \param custom_spaces a collection of custom space indices.
0106    * \param receiver an object that gets the results.
0107    */
0108   void CollectCustomSpaceStatisticsAtLastGC(
0109       std::vector<cppgc::CustomSpaceIndex> custom_spaces,
0110       std::unique_ptr<CustomSpaceStatisticsReceiver> receiver);
0111
0112   /**
0113    * Enables a detached mode that allows testing garbage collection using
0114    * `cppgc::testing` APIs. Once used, the heap cannot be attached to an
0115    * `Isolate` anymore.
0116    */
0117   void EnableDetachedGarbageCollectionsForTesting();
0118
0119   /**
0120    * Performs a stop-the-world garbage collection for testing purposes.
0121    *
0122    * \param stack_state The stack state to assume for the garbage collection.
0123    */
0124   void CollectGarbageForTesting(cppgc::EmbedderStackState stack_state);
0125
0126   /**
0127    * Performs a stop-the-world minor garbage collection for testing purposes.
0128    *
0129    * \param stack_state The stack state to assume for the garbage collection.
0130    */
0131   void CollectGarbageInYoungGenerationForTesting(
0132       cppgc::EmbedderStackState stack_state);
0133
0134  private:
0135   CppHeap() = default;
0136
0137   friend class internal::CppHeap;
0138 };
0139
0140 class JSVisitor : public cppgc::Visitor {
0141  public:
0142   explicit JSVisitor(cppgc::Visitor::Key key) : cppgc::Visitor(key) {}
0143   ~JSVisitor() override = default;
0144
0145   void Trace(const TracedReferenceBase& ref) {
0146     if (ref.IsEmptyThreadSafe()) return;
0147     Visit(ref);
0148   }
0149
0150  protected:
0151   using cppgc::Visitor::Visit;
0152
0153   virtual void Visit(const TracedReferenceBase& ref) {}
0154 };
0155
0156 /**
0157  * Provided as input to `CppHeap::CollectCustomSpaceStatisticsAtLastGC()`.
0158  *
0159  * Its method is invoked with the results of the statistic collection.
0160  */
0161 class CustomSpaceStatisticsReceiver {
0162  public:
0163   virtual ~CustomSpaceStatisticsReceiver() = default;
0164   /**
0165    * Reports the size of a space at the last GC. It is called for each space
0166    * that was requested in `CollectCustomSpaceStatisticsAtLastGC()`.
0167    *
0168    * \param space_index The index of the space.
0169    * \param bytes The total size of live objects in the space at the last GC.
0170    *    It is zero if there was no GC yet.
0171    */
0172   virtual void AllocatedBytes(cppgc::CustomSpaceIndex space_index,
0173                               size_t bytes) = 0;
0174 };
0175
0176 }  // namespace v8
0177
0178 namespace cppgc {
0179
0180 template <typename T>
0181 struct TraceTrait<v8::TracedReference<T>> {
0182   static cppgc::TraceDescriptor GetTraceDescriptor(const void* self) {
0183     return {nullptr, Trace};
0184   }
0185
0186   static void Trace(Visitor* visitor, const void* self) {
0187     static_cast<v8::JSVisitor*>(visitor)->Trace(
0188         *static_cast<const v8::TracedReference<T>*>(self));
0189   }
0190 };
0191
0192 }  // namespace cppgc
0193
0194 #endif  // INCLUDE_V8_CPPGC_H_