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_V8_CPPGC_H_ 6 #define INCLUDE_V8_CPPGC_H_ 7 8 #include <cstdint> 9 #include <memory> 10 #include <vector> 11 12 #include "cppgc/common.h" 13 #include "cppgc/custom-space.h" 14 #include "cppgc/heap-statistics.h" 15 #include "cppgc/visitor.h" 16 #include "v8-internal.h" // NOLINT(build/include_directory) 17 #include "v8-platform.h" // NOLINT(build/include_directory) 18 #include "v8-traced-handle.h" // NOLINT(build/include_directory) 19 20 namespace cppgc { 21 class AllocationHandle; 22 class HeapHandle; 23 } // namespace cppgc 24 25 namespace v8 { 26 27 class Object; 28 29 namespace internal { 30 class CppHeap; 31 } // namespace internal 32 33 class CustomSpaceStatisticsReceiver; 34 35 /** 36 * Describes how V8 wrapper objects maintain references to garbage-collected C++ 37 * objects. 38 */ 39 struct WrapperDescriptor final { 40 /** 41 * The index used on `v8::Ojbect::SetAlignedPointerFromInternalField()` and 42 * related APIs to add additional data to an object which is used to identify 43 * JS->C++ references. 44 */ 45 using InternalFieldIndex = int; 46 47 /** 48 * Unknown embedder id. The value is reserved for internal usages and must not 49 * be used with `CppHeap`. 50 */ 51 static constexpr uint16_t kUnknownEmbedderId = UINT16_MAX; 52 WrapperDescriptorfinal53 constexpr WrapperDescriptor(InternalFieldIndex wrappable_type_index, 54 InternalFieldIndex wrappable_instance_index, 55 uint16_t embedder_id_for_garbage_collected) 56 : wrappable_type_index(wrappable_type_index), 57 wrappable_instance_index(wrappable_instance_index), 58 embedder_id_for_garbage_collected(embedder_id_for_garbage_collected) {} 59 60 /** 61 * Index of the wrappable type. 62 */ 63 InternalFieldIndex wrappable_type_index; 64 65 /** 66 * Index of the wrappable instance. 67 */ 68 InternalFieldIndex wrappable_instance_index; 69 70 /** 71 * Embedder id identifying instances of garbage-collected objects. It is 72 * expected that the first field of the wrappable type is a uint16_t holding 73 * the id. Only references to instances of wrappables types with an id of 74 * `embedder_id_for_garbage_collected` will be considered by CppHeap. 75 */ 76 uint16_t embedder_id_for_garbage_collected; 77 }; 78 79 struct V8_EXPORT CppHeapCreateParams { 80 CppHeapCreateParams(const CppHeapCreateParams&) = delete; 81 CppHeapCreateParams& operator=(const CppHeapCreateParams&) = delete; 82 83 std::vector<std::unique_ptr<cppgc::CustomSpaceBase>> custom_spaces; 84 WrapperDescriptor wrapper_descriptor; 85 }; 86 87 /** 88 * A heap for allocating managed C++ objects. 89 */ 90 class V8_EXPORT CppHeap { 91 public: 92 static std::unique_ptr<CppHeap> Create(v8::Platform* platform, 93 const CppHeapCreateParams& params); 94 95 virtual ~CppHeap() = default; 96 97 /** 98 * \returns the opaque handle for allocating objects using 99 * `MakeGarbageCollected()`. 100 */ 101 cppgc::AllocationHandle& GetAllocationHandle(); 102 103 /** 104 * \returns the opaque heap handle which may be used to refer to this heap in 105 * other APIs. Valid as long as the underlying `CppHeap` is alive. 106 */ 107 cppgc::HeapHandle& GetHeapHandle(); 108 109 /** 110 * Terminate clears all roots and performs multiple garbage collections to 111 * reclaim potentially newly created objects in destructors. 112 * 113 * After this call, object allocation is prohibited. 114 */ 115 void Terminate(); 116 117 /** 118 * \param detail_level specifies whether should return detailed 119 * statistics or only brief summary statistics. 120 * \returns current CppHeap statistics regarding memory consumption 121 * and utilization. 122 */ 123 cppgc::HeapStatistics CollectStatistics( 124 cppgc::HeapStatistics::DetailLevel detail_level); 125 126 /** 127 * Collects statistics for the given spaces and reports them to the receiver. 128 * 129 * \param custom_spaces a collection of custom space indicies. 130 * \param receiver an object that gets the results. 131 */ 132 void CollectCustomSpaceStatisticsAtLastGC( 133 std::vector<cppgc::CustomSpaceIndex> custom_spaces, 134 std::unique_ptr<CustomSpaceStatisticsReceiver> receiver); 135 136 /** 137 * Enables a detached mode that allows testing garbage collection using 138 * `cppgc::testing` APIs. Once used, the heap cannot be attached to an 139 * `Isolate` anymore. 140 */ 141 void EnableDetachedGarbageCollectionsForTesting(); 142 143 /** 144 * Performs a stop-the-world garbage collection for testing purposes. 145 * 146 * \param stack_state The stack state to assume for the garbage collection. 147 */ 148 void CollectGarbageForTesting(cppgc::EmbedderStackState stack_state); 149 150 /** 151 * Performs a stop-the-world minor garbage collection for testing purposes. 152 * 153 * \param stack_state The stack state to assume for the garbage collection. 154 */ 155 void CollectGarbageInYoungGenerationForTesting( 156 cppgc::EmbedderStackState stack_state); 157 158 private: 159 CppHeap() = default; 160 161 friend class internal::CppHeap; 162 }; 163 164 class JSVisitor : public cppgc::Visitor { 165 public: JSVisitor(cppgc::Visitor::Key key)166 explicit JSVisitor(cppgc::Visitor::Key key) : cppgc::Visitor(key) {} 167 ~JSVisitor() override = default; 168 Trace(const TracedReferenceBase & ref)169 void Trace(const TracedReferenceBase& ref) { 170 if (ref.IsEmptyThreadSafe()) return; 171 Visit(ref); 172 } 173 174 protected: 175 using cppgc::Visitor::Visit; 176 Visit(const TracedReferenceBase & ref)177 virtual void Visit(const TracedReferenceBase& ref) {} 178 }; 179 180 /** 181 * Provided as input to `CppHeap::CollectCustomSpaceStatisticsAtLastGC()`. 182 * 183 * Its method is invoked with the results of the statistic collection. 184 */ 185 class CustomSpaceStatisticsReceiver { 186 public: 187 virtual ~CustomSpaceStatisticsReceiver() = default; 188 /** 189 * Reports the size of a space at the last GC. It is called for each space 190 * that was requested in `CollectCustomSpaceStatisticsAtLastGC()`. 191 * 192 * \param space_index The index of the space. 193 * \param bytes The total size of live objects in the space at the last GC. 194 * It is zero if there was no GC yet. 195 */ 196 virtual void AllocatedBytes(cppgc::CustomSpaceIndex space_index, 197 size_t bytes) = 0; 198 }; 199 200 } // namespace v8 201 202 namespace cppgc { 203 204 template <typename T> 205 struct TraceTrait<v8::TracedReference<T>> { 206 static cppgc::TraceDescriptor GetTraceDescriptor(const void* self) { 207 return {nullptr, Trace}; 208 } 209 210 static void Trace(Visitor* visitor, const void* self) { 211 static_cast<v8::JSVisitor*>(visitor)->Trace( 212 *static_cast<const v8::TracedReference<T>*>(self)); 213 } 214 }; 215 216 } // namespace cppgc 217 218 #endif // INCLUDE_V8_CPPGC_H_ 219