v8  9.4.146 (node 16.13.0)
V8 is Google's open source JavaScript engine
heap-consistency.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_CONSISTENCY_H_
6 #define INCLUDE_CPPGC_HEAP_CONSISTENCY_H_
7 
8 #include <cstddef>
9 
10 #include "cppgc/internal/write-barrier.h"
11 #include "cppgc/macros.h"
12 #include "cppgc/trace-trait.h"
13 #include "v8config.h" // NOLINT(build/include_directory)
14 
15 namespace cppgc {
16 
17 class HeapHandle;
18 
19 namespace subtle {
20 
21 /**
22  * **DO NOT USE: Use the appropriate managed types.**
23  *
24  * Consistency helpers that aid in maintaining a consistent internal state of
25  * the garbage collector.
26  */
27 class HeapConsistency final {
28  public:
29  using WriteBarrierParams = internal::WriteBarrier::Params;
30  using WriteBarrierType = internal::WriteBarrier::Type;
31 
32  /**
33  * Gets the required write barrier type for a specific write.
34  *
35  * \param slot Slot containing the pointer to the object. The slot itself
36  * must reside in an object that has been allocated using
37  * `MakeGarbageCollected()`.
38  * \param value The pointer to the object. May be an interior pointer to an
39  * interface of the actual object.
40  * \param params Parameters that may be used for actual write barrier calls.
41  * Only filled if return value indicates that a write barrier is needed. The
42  * contents of the `params` are an implementation detail.
43  * \returns whether a write barrier is needed and which barrier to invoke.
44  */
45  static V8_INLINE WriteBarrierType GetWriteBarrierType(
46  const void* slot, const void* value, WriteBarrierParams& params) {
47  return internal::WriteBarrier::GetWriteBarrierType(slot, value, params);
48  }
49 
50  /**
51  * Gets the required write barrier type for a specific write.
52  *
53  * \param slot Slot to some part of an object. The object must not necessarily
54  have been allocated using `MakeGarbageCollected()` but can also live
55  off-heap or on stack.
56  * \param params Parameters that may be used for actual write barrier calls.
57  * Only filled if return value indicates that a write barrier is needed. The
58  * contents of the `params` are an implementation detail.
59  * \param callback Callback returning the corresponding heap handle. The
60  * callback is only invoked if the heap cannot otherwise be figured out. The
61  * callback must not allocate.
62  * \returns whether a write barrier is needed and which barrier to invoke.
63  */
64  template <typename HeapHandleCallback>
65  static V8_INLINE WriteBarrierType
66  GetWriteBarrierType(const void* slot, WriteBarrierParams& params,
67  HeapHandleCallback callback) {
68  return internal::WriteBarrier::GetWriteBarrierType(slot, params, callback);
69  }
70 
71  /**
72  * Conservative Dijkstra-style write barrier that processes an object if it
73  * has not yet been processed.
74  *
75  * \param params The parameters retrieved from `GetWriteBarrierType()`.
76  * \param object The pointer to the object. May be an interior pointer to a
77  * an interface of the actual object.
78  */
79  static V8_INLINE void DijkstraWriteBarrier(const WriteBarrierParams& params,
80  const void* object) {
81  internal::WriteBarrier::DijkstraMarkingBarrier(params, object);
82  }
83 
84  /**
85  * Conservative Dijkstra-style write barrier that processes a range of
86  * elements if they have not yet been processed.
87  *
88  * \param params The parameters retrieved from `GetWriteBarrierType()`.
89  * \param first_element Pointer to the first element that should be processed.
90  * The slot itself must reside in an object that has been allocated using
91  * `MakeGarbageCollected()`.
92  * \param element_size Size of the element in bytes.
93  * \param number_of_elements Number of elements that should be processed,
94  * starting with `first_element`.
95  * \param trace_callback The trace callback that should be invoked for each
96  * element if necessary.
97  */
99  const WriteBarrierParams& params, const void* first_element,
100  size_t element_size, size_t number_of_elements,
101  TraceCallback trace_callback) {
103  params, first_element, element_size, number_of_elements,
104  trace_callback);
105  }
106 
107  /**
108  * Steele-style write barrier that re-processes an object if it has already
109  * been processed.
110  *
111  * \param params The parameters retrieved from `GetWriteBarrierType()`.
112  * \param object The pointer to the object which must point to an object that
113  * has been allocated using `MakeGarbageCollected()`. Interior pointers are
114  * not supported.
115  */
116  static V8_INLINE void SteeleWriteBarrier(const WriteBarrierParams& params,
117  const void* object) {
118  internal::WriteBarrier::SteeleMarkingBarrier(params, object);
119  }
120 
121  /**
122  * Generational barrier for maintaining consistency when running with multiple
123  * generations.
124  *
125  * \param params The parameters retrieved from `GetWriteBarrierType()`.
126  * \param slot Slot containing the pointer to the object. The slot itself
127  * must reside in an object that has been allocated using
128  * `MakeGarbageCollected()`.
129  */
130  static V8_INLINE void GenerationalBarrier(const WriteBarrierParams& params,
131  const void* slot) {
132  internal::WriteBarrier::GenerationalBarrier(params, slot);
133  }
134 
135  private:
136  HeapConsistency() = delete;
137 };
138 
139 /**
140  * Disallows garbage collection finalizations. Any garbage collection triggers
141  * result in a crash when in this scope.
142  *
143  * Note that the garbage collector already covers paths that can lead to garbage
144  * collections, so user code does not require checking
145  * `IsGarbageCollectionAllowed()` before allocations.
146  */
147 class V8_EXPORT V8_NODISCARD DisallowGarbageCollectionScope final {
149 
150  public:
151  /**
152  * \returns whether garbage collections are currently allowed.
153  */
154  static bool IsGarbageCollectionAllowed(HeapHandle& heap_handle);
155 
156  /**
157  * Enters a disallow garbage collection scope. Must be paired with `Leave()`.
158  * Prefer a scope instance of `DisallowGarbageCollectionScope`.
159  *
160  * \param heap_handle The corresponding heap.
161  */
162  static void Enter(HeapHandle& heap_handle);
163 
164  /**
165  * Leaves a disallow garbage collection scope. Must be paired with `Enter()`.
166  * Prefer a scope instance of `DisallowGarbageCollectionScope`.
167  *
168  * \param heap_handle The corresponding heap.
169  */
170  static void Leave(HeapHandle& heap_handle);
171 
172  /**
173  * Constructs a scoped object that automatically enters and leaves a disallow
174  * garbage collection scope based on its lifetime.
175  *
176  * \param heap_handle The corresponding heap.
177  */
178  explicit DisallowGarbageCollectionScope(HeapHandle& heap_handle);
180 
181  DisallowGarbageCollectionScope(const DisallowGarbageCollectionScope&) =
182  delete;
183  DisallowGarbageCollectionScope& operator=(
184  const DisallowGarbageCollectionScope&) = delete;
185 
186  private:
187  HeapHandle& heap_handle_;
188 };
189 
190 /**
191  * Avoids invoking garbage collection finalizations. Already running garbage
192  * collection phase are unaffected by this scope.
193  *
194  * Should only be used temporarily as the scope has an impact on memory usage
195  * and follow up garbage collections.
196  */
197 class V8_EXPORT V8_NODISCARD NoGarbageCollectionScope final {
199 
200  public:
201  /**
202  * Enters a no garbage collection scope. Must be paired with `Leave()`. Prefer
203  * a scope instance of `NoGarbageCollectionScope`.
204  *
205  * \param heap_handle The corresponding heap.
206  */
207  static void Enter(HeapHandle& heap_handle);
208 
209  /**
210  * Leaves a no garbage collection scope. Must be paired with `Enter()`. Prefer
211  * a scope instance of `NoGarbageCollectionScope`.
212  *
213  * \param heap_handle The corresponding heap.
214  */
215  static void Leave(HeapHandle& heap_handle);
216 
217  /**
218  * Constructs a scoped object that automatically enters and leaves a no
219  * garbage collection scope based on its lifetime.
220  *
221  * \param heap_handle The corresponding heap.
222  */
223  explicit NoGarbageCollectionScope(HeapHandle& heap_handle);
225 
226  NoGarbageCollectionScope(const NoGarbageCollectionScope&) = delete;
227  NoGarbageCollectionScope& operator=(const NoGarbageCollectionScope&) = delete;
228 
229  private:
230  HeapHandle& heap_handle_;
231 };
232 
233 } // namespace subtle
234 } // namespace cppgc
235 
236 #endif // INCLUDE_CPPGC_HEAP_CONSISTENCY_H_