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 <memory> 9 #include <vector> 10 11 #include "cppgc/common.h" 12 #include "cppgc/custom-space.h" 13 #include "cppgc/platform.h" 14 #include "v8config.h" // NOLINT(build/include_directory) 15 16 /** 17 * cppgc - A C++ garbage collection library. 18 */ 19 namespace cppgc { 20 21 class AllocationHandle; 22 23 /** 24 * Implementation details of cppgc. Those details are considered internal and 25 * may change at any point in time without notice. Users should never rely on 26 * the contents of this namespace. 27 */ 28 namespace internal { 29 class Heap; 30 } // namespace internal 31 32 class V8_EXPORT Heap { 33 public: 34 /** 35 * Specifies the stack state the embedder is in. 36 */ 37 using StackState = EmbedderStackState; 38 39 /** 40 * Specifies whether conservative stack scanning is supported. 41 */ 42 enum class StackSupport : uint8_t { 43 /** 44 * Conservative stack scan is supported. 45 */ 46 kSupportsConservativeStackScan, 47 /** 48 * Conservative stack scan is not supported. Embedders may use this option 49 * when using custom infrastructure that is unsupported by the library. 50 */ 51 kNoConservativeStackScan, 52 }; 53 54 /** 55 * Constraints for a Heap setup. 56 */ 57 struct ResourceConstraints { 58 /** 59 * Allows the heap to grow to some initial size in bytes before triggering 60 * garbage collections. This is useful when it is known that applications 61 * need a certain minimum heap to run to avoid repeatedly invoking the 62 * garbage collector when growing the heap. 63 */ 64 size_t initial_heap_size_bytes = 0; 65 }; 66 67 /** 68 * Options specifying Heap properties (e.g. custom spaces) when initializing a 69 * heap through `Heap::Create()`. 70 */ 71 struct HeapOptions { 72 /** 73 * Creates reasonable defaults for instantiating a Heap. 74 * 75 * \returns the HeapOptions that can be passed to `Heap::Create()`. 76 */ DefaultHeapOptions77 static HeapOptions Default() { return {}; } 78 79 /** 80 * Custom spaces added to heap are required to have indices forming a 81 * numbered sequence starting at 0, i.e., their `kSpaceIndex` must 82 * correspond to the index they reside in the vector. 83 */ 84 std::vector<std::unique_ptr<CustomSpaceBase>> custom_spaces; 85 86 /** 87 * Specifies whether conservative stack scan is supported. When conservative 88 * stack scan is not supported, the collector may try to invoke 89 * garbage collections using non-nestable task, which are guaranteed to have 90 * no interesting stack, through the provided Platform. If such tasks are 91 * not supported by the Platform, the embedder must take care of invoking 92 * the GC through `ForceGarbageCollectionSlow()`. 93 */ 94 StackSupport stack_support = StackSupport::kSupportsConservativeStackScan; 95 96 /** 97 * Resource constraints specifying various properties that the internal 98 * GC scheduler follows. 99 */ 100 ResourceConstraints resource_constraints; 101 }; 102 103 /** 104 * Creates a new heap that can be used for object allocation. 105 * 106 * \param platform implemented and provided by the embedder. 107 * \param options HeapOptions specifying various properties for the Heap. 108 * \returns a new Heap instance. 109 */ 110 static std::unique_ptr<Heap> Create( 111 std::shared_ptr<Platform> platform, 112 HeapOptions options = HeapOptions::Default()); 113 114 virtual ~Heap() = default; 115 116 /** 117 * Forces garbage collection. 118 * 119 * \param source String specifying the source (or caller) triggering a 120 * forced garbage collection. 121 * \param reason String specifying the reason for the forced garbage 122 * collection. 123 * \param stack_state The embedder stack state, see StackState. 124 */ 125 void ForceGarbageCollectionSlow( 126 const char* source, const char* reason, 127 StackState stack_state = StackState::kMayContainHeapPointers); 128 129 /** 130 * \returns the opaque handle for allocating objects using 131 * `MakeGarbageCollected()`. 132 */ 133 AllocationHandle& GetAllocationHandle(); 134 135 private: 136 Heap() = default; 137 138 friend class internal::Heap; 139 }; 140 141 } // namespace cppgc 142 143 #endif // INCLUDE_CPPGC_HEAP_H_ 144