v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
explicit-management.h
Go to the documentation of this file.
1 // Copyright 2021 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_EXPLICIT_MANAGEMENT_H_
6 #define INCLUDE_CPPGC_EXPLICIT_MANAGEMENT_H_
7 
8 #include <cstddef>
9 
10 #include "cppgc/allocation.h"
11 #include "cppgc/internal/logging.h"
12 #include "cppgc/type-traits.h"
13 
14 namespace cppgc {
15 
16 class HeapHandle;
17 
18 namespace subtle {
19 
20 template <typename T>
21 void FreeUnreferencedObject(HeapHandle& heap_handle, T& object);
22 template <typename T>
23 bool Resize(T& object, AdditionalBytes additional_bytes);
24 
25 } // namespace subtle
26 
27 namespace internal {
28 
29 class ExplicitManagementImpl final {
30  private:
31  V8_EXPORT static void FreeUnreferencedObject(HeapHandle&, void*);
32  V8_EXPORT static bool Resize(void*, size_t);
33 
34  template <typename T>
35  friend void subtle::FreeUnreferencedObject(HeapHandle&, T&);
36  template <typename T>
37  friend bool subtle::Resize(T&, AdditionalBytes);
38 };
39 } // namespace internal
40 
41 namespace subtle {
42 
43 /**
44  * Informs the garbage collector that `object` can be immediately reclaimed. The
45  * destructor may not be invoked immediately but only on next garbage
46  * collection.
47  *
48  * It is up to the embedder to guarantee that no other object holds a reference
49  * to `object` after calling `FreeUnreferencedObject()`. In case such a
50  * reference exists, it's use results in a use-after-free.
51  *
52  * To aid in using the API, `FreeUnreferencedObject()` may be called from
53  * destructors on objects that would be reclaimed in the same garbage collection
54  * cycle.
55  *
56  * \param heap_handle The corresponding heap.
57  * \param object Reference to an object that is of type `GarbageCollected` and
58  * should be immediately reclaimed.
59  */
60 template <typename T>
61 void FreeUnreferencedObject(HeapHandle& heap_handle, T& object) {
62  static_assert(IsGarbageCollectedTypeV<T>,
63  "Object must be of type GarbageCollected.");
64  internal::ExplicitManagementImpl::FreeUnreferencedObject(heap_handle,
65  &object);
66 }
67 
68 /**
69  * Tries to resize `object` of type `T` with additional bytes on top of
70  * sizeof(T). Resizing is only useful with trailing inlined storage, see e.g.
71  * `MakeGarbageCollected(AllocationHandle&, AdditionalBytes)`.
72  *
73  * `Resize()` performs growing or shrinking as needed and may skip the operation
74  * for internal reasons, see return value.
75  *
76  * It is up to the embedder to guarantee that in case of shrinking a larger
77  * object down, the reclaimed area is not used anymore. Any subsequent use
78  * results in a use-after-free.
79  *
80  * The `object` must be live when calling `Resize()`.
81  *
82  * \param object Reference to an object that is of type `GarbageCollected` and
83  * should be resized.
84  * \param additional_bytes Bytes in addition to sizeof(T) that the object should
85  * provide.
86  * \returns true when the operation was successful and the result can be relied
87  * on, and false otherwise.
88  */
89 template <typename T>
90 bool Resize(T& object, AdditionalBytes additional_bytes) {
91  static_assert(IsGarbageCollectedTypeV<T>,
92  "Object must be of type GarbageCollected.");
93  return internal::ExplicitManagementImpl::Resize(
94  &object, sizeof(T) + additional_bytes.value);
95 }
96 
97 } // namespace subtle
98 } // namespace cppgc
99 
100 #endif // INCLUDE_CPPGC_EXPLICIT_MANAGEMENT_H_