v8  10.1.124 (node 18.2.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 <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  */
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  */
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  */
75  /**
76  * Incremental and concurrent marking.
77  */
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  */
94  /**
95  * Incremental and concurrent sweeping. Sweeping is split and interleaved
96  * with the rest of the application.
97  */
99  };
100 
101  /**
102  * Constraints for a Heap setup.
103  */
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  */
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  */
124  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  */
142 
143  /**
144  * Specifies which types of marking are supported by the heap.
145  */
147 
148  /**
149  * Specifies which types of sweeping are supported by the heap.
150  */
152 
153  /**
154  * Resource constraints specifying various properties that the internal
155  * GC scheduler follows.
156  */
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,
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  */
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_