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