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_CPPGC_HEAP_H_ 6 #define INCLUDE_CPPGC_HEAP_H_ 7 8 #include <cstddef> 9 #include <cstdint> 10 #include <memory> 11 #include <vector> 12 13 #include "cppgc/common.h" 14 #include "cppgc/custom-space.h" 15 #include "cppgc/platform.h" 16 #include "v8config.h" // NOLINT(build/include_directory) 17 18 /** 19 * cppgc - A C++ garbage collection library. 20 */ 21 namespace cppgc { 22 23 class AllocationHandle; 24 25 /** 26 * Implementation details of cppgc. Those details are considered internal and 27 * may change at any point in time without notice. Users should never rely on 28 * the contents of this namespace. 29 */ 30 namespace internal { 31 class Heap; 32 } // namespace internal 33 34 /** 35 * Used for additional heap APIs. 36 */ 37 class HeapHandle; 38 39 class V8_EXPORT Heap { 40 public: 41 /** 42 * Specifies the stack state the embedder is in. 43 */ 44 using StackState = EmbedderStackState; 45 46 /** 47 * Specifies whether conservative stack scanning is supported. 48 */ 49 enum class StackSupport : uint8_t { 50 /** 51 * Conservative stack scan is supported. 52 */ 53 kSupportsConservativeStackScan, 54 /** 55 * Conservative stack scan is not supported. Embedders may use this option 56 * when using custom infrastructure that is unsupported by the library. 57 */ 58 kNoConservativeStackScan, 59 }; 60 61 /** 62 * Specifies supported marking types 63 */ 64 enum class MarkingType : uint8_t { 65 /** 66 * Atomic stop-the-world marking. This option does not require any write 67 * barriers but is the most intrusive in terms of jank. 68 */ 69 kAtomic, 70 /** 71 * Incremental marking interleaves marking with the rest of the application 72 * workload on the same thread. 73 */ 74 kIncremental, 75 /** 76 * Incremental and concurrent marking. 77 */ 78 kIncrementalAndConcurrent 79 }; 80 81 /** 82 * Specifies supported sweeping types 83 */ 84 enum class SweepingType : uint8_t { 85 /** 86 * Atomic stop-the-world sweeping. All of sweeping is performed at once. 87 */ 88 kAtomic, 89 /** 90 * Incremental sweeping interleaves sweeping with the rest of the 91 * application workload on the same thread. 92 */ 93 kIncremental, 94 /** 95 * Incremental and concurrent sweeping. Sweeping is split and interleaved 96 * with the rest of the application. 97 */ 98 kIncrementalAndConcurrent 99 }; 100 101 /** 102 * Constraints for a Heap setup. 103 */ 104 struct ResourceConstraints { 105 /** 106 * Allows the heap to grow to some initial size in bytes before triggering 107 * garbage collections. This is useful when it is known that applications 108 * need a certain minimum heap to run to avoid repeatedly invoking the 109 * garbage collector when growing the heap. 110 */ 111 size_t initial_heap_size_bytes = 0; 112 }; 113 114 /** 115 * Options specifying Heap properties (e.g. custom spaces) when initializing a 116 * heap through `Heap::Create()`. 117 */ 118 struct HeapOptions { 119 /** 120 * Creates reasonable defaults for instantiating a Heap. 121 * 122 * \returns the HeapOptions that can be passed to `Heap::Create()`. 123 */ DefaultHeapOptions124 static HeapOptions Default() { return {}; } 125 126 /** 127 * Custom spaces added to heap are required to have indices forming a 128 * numbered sequence starting at 0, i.e., their `kSpaceIndex` must 129 * correspond to the index they reside in the vector. 130 */ 131 std::vector<std::unique_ptr<CustomSpaceBase>> custom_spaces; 132 133 /** 134 * Specifies whether conservative stack scan is supported. When conservative 135 * stack scan is not supported, the collector may try to invoke 136 * garbage collections using non-nestable task, which are guaranteed to have 137 * no interesting stack, through the provided Platform. If such tasks are 138 * not supported by the Platform, the embedder must take care of invoking 139 * the GC through `ForceGarbageCollectionSlow()`. 140 */ 141 StackSupport stack_support = StackSupport::kSupportsConservativeStackScan; 142 143 /** 144 * Specifies which types of marking are supported by the heap. 145 */ 146 MarkingType marking_support = MarkingType::kIncrementalAndConcurrent; 147 148 /** 149 * Specifies which types of sweeping are supported by the heap. 150 */ 151 SweepingType sweeping_support = SweepingType::kIncrementalAndConcurrent; 152 153 /** 154 * Resource constraints specifying various properties that the internal 155 * GC scheduler follows. 156 */ 157 ResourceConstraints resource_constraints; 158 }; 159 160 /** 161 * Creates a new heap that can be used for object allocation. 162 * 163 * \param platform implemented and provided by the embedder. 164 * \param options HeapOptions specifying various properties for the Heap. 165 * \returns a new Heap instance. 166 */ 167 static std::unique_ptr<Heap> Create( 168 std::shared_ptr<Platform> platform, 169 HeapOptions options = HeapOptions::Default()); 170 171 virtual ~Heap() = default; 172 173 /** 174 * Forces garbage collection. 175 * 176 * \param source String specifying the source (or caller) triggering a 177 * forced garbage collection. 178 * \param reason String specifying the reason for the forced garbage 179 * collection. 180 * \param stack_state The embedder stack state, see StackState. 181 */ 182 void ForceGarbageCollectionSlow( 183 const char* source, const char* reason, 184 StackState stack_state = StackState::kMayContainHeapPointers); 185 186 /** 187 * \returns the opaque handle for allocating objects using 188 * `MakeGarbageCollected()`. 189 */ 190 AllocationHandle& GetAllocationHandle(); 191 192 /** 193 * \returns the opaque heap handle which may be used to refer to this heap in 194 * other APIs. Valid as long as the underlying `Heap` is alive. 195 */ 196 HeapHandle& GetHeapHandle(); 197 198 private: 199 Heap() = default; 200 201 friend class internal::Heap; 202 }; 203 204 } // namespace cppgc 205 206 #endif // INCLUDE_CPPGC_HEAP_H_ 207