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>
FreeUnreferencedObject(HeapHandle& heap_handle, T& object)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>
Resize(T& object, AdditionalBytes additional_bytes)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_
101