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 /**
0036  * Describes how V8 wrapper objects maintain references to garbage-collected C++
0037  * objects.
0038  */
0039 struct WrapperDescriptor final {
0040   /**
0041    * The index used on `v8::Ojbect::SetAlignedPointerFromInternalField()` and
0042    * related APIs to add additional data to an object which is used to identify
0043    * JS->C++ references.
0044    */
0045   using InternalFieldIndex = int;
0046
0047   /**
0048    * Unknown embedder id. The value is reserved for internal usages and must not
0049    * be used with `CppHeap`.
0050    */
0051   static constexpr uint16_t kUnknownEmbedderId = UINT16_MAX;
0052
0053   constexpr WrapperDescriptor(InternalFieldIndex wrappable_type_index,
0054                               InternalFieldIndex wrappable_instance_index,
0055                               uint16_t embedder_id_for_garbage_collected)
0056       : wrappable_type_index(wrappable_type_index),
0057         wrappable_instance_index(wrappable_instance_index),
0058         embedder_id_for_garbage_collected(embedder_id_for_garbage_collected) {}
0059
0060   /**
0061    * Index of the wrappable type.
0062    */
0063   InternalFieldIndex wrappable_type_index;
0064
0065   /**
0066    * Index of the wrappable instance.
0067    */
0068   InternalFieldIndex wrappable_instance_index;
0069
0070   /**
0071    * Embedder id identifying instances of garbage-collected objects. It is
0072    * expected that the first field of the wrappable type is a uint16_t holding
0073    * the id. Only references to instances of wrappables types with an id of
0074    * `embedder_id_for_garbage_collected` will be considered by CppHeap.
0075    */
0076   uint16_t embedder_id_for_garbage_collected;
0077 };
0078
0079 struct V8_EXPORT CppHeapCreateParams {
0080   CppHeapCreateParams(
0081       std::vector<std::unique_ptr<cppgc::CustomSpaceBase>> custom_spaces,
0082       WrapperDescriptor wrapper_descriptor)
0083       : custom_spaces(std::move(custom_spaces)),
0084         wrapper_descriptor(wrapper_descriptor) {}
0085
0086   CppHeapCreateParams(const CppHeapCreateParams&) = delete;
0087   CppHeapCreateParams& operator=(const CppHeapCreateParams&) = delete;
0088
0089   std::vector<std::unique_ptr<cppgc::CustomSpaceBase>> custom_spaces;
0090   WrapperDescriptor wrapper_descriptor;
0091   /**
0092    * Specifies which kind of marking are supported by the heap. The type may be
0093    * further reduced via runtime flags when attaching the heap to an Isolate.
0094    */
0095   cppgc::Heap::MarkingType marking_support =
0096       cppgc::Heap::MarkingType::kIncrementalAndConcurrent;
0097   /**
0098    * Specifies which kind of sweeping is supported by the heap. The type may be
0099    * further reduced via runtime flags when attaching the heap to an Isolate.
0100    */
0101   cppgc::Heap::SweepingType sweeping_support =
0102       cppgc::Heap::SweepingType::kIncrementalAndConcurrent;
0103 };
0104
0105 /**
0106  * A heap for allocating managed C++ objects.
0107  *
0108  * Similar to v8::Isolate, the heap may only be accessed from one thread at a
0109  * time. The heap may be used from different threads using the
0110  * v8::Locker/v8::Unlocker APIs which is different from generic Oilpan.
0111  */
0112 class V8_EXPORT CppHeap {
0113  public:
0114   static std::unique_ptr<CppHeap> Create(v8::Platform* platform,
0115                                          const CppHeapCreateParams& params);
0116
0117   virtual ~CppHeap() = default;
0118
0119   /**
0120    * \returns the opaque handle for allocating objects using
0121    * `MakeGarbageCollected()`.
0122    */
0123   cppgc::AllocationHandle& GetAllocationHandle();
0124
0125   /**
0126    * \returns the opaque heap handle which may be used to refer to this heap in
0127    *   other APIs. Valid as long as the underlying `CppHeap` is alive.
0128    */
0129   cppgc::HeapHandle& GetHeapHandle();
0130
0131   /**
0132    * Terminate clears all roots and performs multiple garbage collections to
0133    * reclaim potentially newly created objects in destructors.
0134    *
0135    * After this call, object allocation is prohibited.
0136    */
0137   void Terminate();
0138
0139   /**
0140    * \param detail_level specifies whether should return detailed
0141    *   statistics or only brief summary statistics.
0142    * \returns current CppHeap statistics regarding memory consumption
0143    *   and utilization.
0144    */
0145   cppgc::HeapStatistics CollectStatistics(
0146       cppgc::HeapStatistics::DetailLevel detail_level);
0147
0148   /**
0149    * Collects statistics for the given spaces and reports them to the receiver.
0150    *
0151    * \param custom_spaces a collection of custom space indicies.
0152    * \param receiver an object that gets the results.
0153    */
0154   void CollectCustomSpaceStatisticsAtLastGC(
0155       std::vector<cppgc::CustomSpaceIndex> custom_spaces,
0156       std::unique_ptr<CustomSpaceStatisticsReceiver> receiver);
0157
0158   /**
0159    * Enables a detached mode that allows testing garbage collection using
0160    * `cppgc::testing` APIs. Once used, the heap cannot be attached to an
0161    * `Isolate` anymore.
0162    */
0163   void EnableDetachedGarbageCollectionsForTesting();
0164
0165   /**
0166    * Performs a stop-the-world garbage collection for testing purposes.
0167    *
0168    * \param stack_state The stack state to assume for the garbage collection.
0169    */
0170   void CollectGarbageForTesting(cppgc::EmbedderStackState stack_state);
0171
0172   /**
0173    * Performs a stop-the-world minor garbage collection for testing purposes.
0174    *
0175    * \param stack_state The stack state to assume for the garbage collection.
0176    */
0177   void CollectGarbageInYoungGenerationForTesting(
0178       cppgc::EmbedderStackState stack_state);
0179
0180   /**
0181    * \returns the wrapper descriptor of this CppHeap.
0182    */
0183   v8::WrapperDescriptor wrapper_descriptor() const;
0184
0185  private:
0186   CppHeap() = default;
0187
0188   friend class internal::CppHeap;
0189 };
0190
0191 class JSVisitor : public cppgc::Visitor {
0192  public:
0193   explicit JSVisitor(cppgc::Visitor::Key key) : cppgc::Visitor(key) {}
0194   ~JSVisitor() override = default;
0195
0196   void Trace(const TracedReferenceBase& ref) {
0197     if (ref.IsEmptyThreadSafe()) return;
0198     Visit(ref);
0199   }
0200
0201  protected:
0202   using cppgc::Visitor::Visit;
0203
0204   virtual void Visit(const TracedReferenceBase& ref) {}
0205 };
0206
0207 /**
0208  * Provided as input to `CppHeap::CollectCustomSpaceStatisticsAtLastGC()`.
0209  *
0210  * Its method is invoked with the results of the statistic collection.
0211  */
0212 class CustomSpaceStatisticsReceiver {
0213  public:
0214   virtual ~CustomSpaceStatisticsReceiver() = default;
0215   /**
0216    * Reports the size of a space at the last GC. It is called for each space
0217    * that was requested in `CollectCustomSpaceStatisticsAtLastGC()`.
0218    *
0219    * \param space_index The index of the space.
0220    * \param bytes The total size of live objects in the space at the last GC.
0221    *    It is zero if there was no GC yet.
0222    */
0223   virtual void AllocatedBytes(cppgc::CustomSpaceIndex space_index,
0224                               size_t bytes) = 0;
0225 };
0226
0227 }  // namespace v8
0228
0229 namespace cppgc {
0230
0231 template <typename T>
0232 struct TraceTrait<v8::TracedReference<T>> {
0233   static cppgc::TraceDescriptor GetTraceDescriptor(const void* self) {
0234     return {nullptr, Trace};
0235   }
0236
0237   static void Trace(Visitor* visitor, const void* self) {
0238     static_cast<v8::JSVisitor*>(visitor)->Trace(
0239         *static_cast<const v8::TracedReference<T>*>(self));
0240   }
0241 };
0242
0243 }  // namespace cppgc
0244
0245 #endif  // INCLUDE_V8_CPPGC_H_