v8  9.0.257(node16.0.0)
V8 is Google's open source JavaScript engine
allocation.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_ALLOCATION_H_
6 #define INCLUDE_CPPGC_ALLOCATION_H_
7 
8 #include <stdint.h>
9 
10 #include <atomic>
11 
12 #include "cppgc/custom-space.h"
13 #include "cppgc/garbage-collected.h"
14 #include "cppgc/internal/api-constants.h"
15 #include "cppgc/internal/gc-info.h"
16 
17 namespace cppgc {
18 
19 template <typename T>
20 class MakeGarbageCollectedTraitBase;
21 
22 namespace internal {
23 class ObjectAllocator;
24 } // namespace internal
25 
26 /**
27  * AllocationHandle is used to allocate garbage-collected objects.
28  */
29 class AllocationHandle;
30 
31 namespace internal {
32 
34  protected:
35  static inline void MarkObjectAsFullyConstructed(const void* payload) {
36  // See api_constants for an explanation of the constants.
37  std::atomic<uint16_t>* atomic_mutable_bitfield =
38  reinterpret_cast<std::atomic<uint16_t>*>(
39  const_cast<uint16_t*>(reinterpret_cast<const uint16_t*>(
40  reinterpret_cast<const uint8_t*>(payload) -
41  api_constants::kFullyConstructedBitFieldOffsetFromPayload)));
42  atomic_mutable_bitfield->fetch_or(api_constants::kFullyConstructedBitMask,
43  std::memory_order_release);
44  }
45 
46  static void* Allocate(cppgc::AllocationHandle& handle, size_t size,
47  GCInfoIndex index);
48  static void* Allocate(cppgc::AllocationHandle& handle, size_t size,
49  GCInfoIndex index, CustomSpaceIndex space_index);
50 
51  friend class HeapObjectHeader;
52 };
53 
54 } // namespace internal
55 
56 /**
57  * Base trait that provides utilities for advancers users that have custom
58  * allocation needs (e.g., overriding size). It's expected that users override
59  * MakeGarbageCollectedTrait (see below) and inherit from
60  * MakeGarbageCollectedTraitBase and make use of the low-level primitives
61  * offered to allocate and construct an object.
62  */
63 template <typename T>
64 class MakeGarbageCollectedTraitBase
66  private:
67  static_assert(internal::IsGarbageCollectedType<T>::value,
68  "T needs to be a garbage collected object");
69  static_assert(!IsGarbageCollectedWithMixinTypeV<T> ||
70  sizeof(T) <=
71  internal::api_constants::kLargeObjectSizeThreshold,
72  "GarbageCollectedMixin may not be a large object");
73 
74  template <typename U, typename CustomSpace>
75  struct SpacePolicy {
76  static void* Allocate(AllocationHandle& handle, size_t size) {
77  // Custom space.
78  static_assert(std::is_base_of<CustomSpaceBase, CustomSpace>::value,
79  "Custom space must inherit from CustomSpaceBase.");
81  handle, size, internal::GCInfoTrait<T>::Index(),
82  CustomSpace::kSpaceIndex);
83  }
84  };
85 
86  template <typename U>
87  struct SpacePolicy<U, void> {
88  static void* Allocate(AllocationHandle& handle, size_t size) {
89  // Default space.
91  handle, size, internal::GCInfoTrait<T>::Index());
92  }
93  };
94 
95  protected:
96  /**
97  * Allocates memory for an object of type T.
98  *
99  * \param handle AllocationHandle identifying the heap to allocate the object
100  * on.
101  * \param size The size that should be reserved for the object.
102  * \returns the memory to construct an object of type T on.
103  */
104  static void* Allocate(AllocationHandle& handle, size_t size) {
105  return SpacePolicy<T, typename SpaceTrait<T>::Space>::Allocate(handle,
106  size);
107  }
108 
109  /**
110  * Marks an object as fully constructed, resulting in precise handling by the
111  * garbage collector.
112  *
113  * \param payload The base pointer the object is allocated at.
114  */
115  static void MarkObjectAsFullyConstructed(const void* payload) {
117  payload);
118  }
119 };
120 
121 /**
122  * Passed to MakeGarbageCollected to specify how many bytes should be appended
123  * to the allocated object.
124  *
125  * Example:
126  * \code
127  * class InlinedArray final : public GarbageCollected<InlinedArray> {
128  * public:
129  * explicit InlinedArray(size_t bytes) : size(bytes), byte_array(this + 1) {}
130  * void Trace(Visitor*) const {}
131 
132  * size_t size;
133  * char* byte_array;
134  * };
135  *
136  * auto* inlined_array = MakeGarbageCollected<InlinedArray(
137  * GetAllocationHandle(), AdditionalBytes(4), 4);
138  * for (size_t i = 0; i < 4; i++) {
139  * Process(inlined_array->byte_array[i]);
140  * }
141  * \endcode
142  */
144  constexpr explicit AdditionalBytes(size_t bytes) : value(bytes) {}
145  const size_t value;
146 };
147 
148 /**
149  * Default trait class that specifies how to construct an object of type T.
150  * Advanced users may override how an object is constructed using the utilities
151  * that are provided through MakeGarbageCollectedTraitBase.
152  *
153  * Any trait overriding construction must
154  * - allocate through `MakeGarbageCollectedTraitBase<T>::Allocate`;
155  * - mark the object as fully constructed using
156  * `MakeGarbageCollectedTraitBase<T>::MarkObjectAsFullyConstructed`;
157  */
158 template <typename T>
159 class MakeGarbageCollectedTrait : public MakeGarbageCollectedTraitBase<T> {
160  public:
161  template <typename... Args>
162  static T* Call(AllocationHandle& handle, Args&&... args) {
163  void* memory =
164  MakeGarbageCollectedTraitBase<T>::Allocate(handle, sizeof(T));
165  T* object = ::new (memory) T(std::forward<Args>(args)...);
166  MakeGarbageCollectedTraitBase<T>::MarkObjectAsFullyConstructed(object);
167  return object;
168  }
169 
170  template <typename... Args>
171  static T* Call(AllocationHandle& handle, AdditionalBytes additional_bytes,
172  Args&&... args) {
173  void* memory = MakeGarbageCollectedTraitBase<T>::Allocate(
174  handle, sizeof(T) + additional_bytes.value);
175  T* object = ::new (memory) T(std::forward<Args>(args)...);
176  MakeGarbageCollectedTraitBase<T>::MarkObjectAsFullyConstructed(object);
177  return object;
178  }
179 };
180 
181 /**
182  * Allows users to specify a post-construction callback for specific types. The
183  * callback is invoked on the instance of type T right after it has been
184  * constructed. This can be useful when the callback requires a
185  * fully-constructed object to be able to dispatch to virtual methods.
186  */
187 template <typename T, typename = void>
189  static void Call(T*) {}
190 };
191 
192 /**
193  * Constructs a managed object of type T where T transitively inherits from
194  * GarbageCollected.
195  *
196  * \param args List of arguments with which an instance of T will be
197  * constructed.
198  * \returns an instance of type T.
199  */
200 template <typename T, typename... Args>
201 T* MakeGarbageCollected(AllocationHandle& handle, Args&&... args) {
202  T* object =
203  MakeGarbageCollectedTrait<T>::Call(handle, std::forward<Args>(args)...);
204  PostConstructionCallbackTrait<T>::Call(object);
205  return object;
206 }
207 
208 /**
209  * Constructs a managed object of type T where T transitively inherits from
210  * GarbageCollected. Created objects will have additional bytes appended to
211  * it. Allocated memory would suffice for `sizeof(T) + additional_bytes`.
212  *
213  * \param additional_bytes Denotes how many bytes to append to T.
214  * \param args List of arguments with which an instance of T will be
215  * constructed.
216  * \returns an instance of type T.
217  */
218 template <typename T, typename... Args>
219 T* MakeGarbageCollected(AllocationHandle& handle,
220  AdditionalBytes additional_bytes, Args&&... args) {
221  T* object = MakeGarbageCollectedTrait<T>::Call(handle, additional_bytes,
222  std::forward<Args>(args)...);
223  PostConstructionCallbackTrait<T>::Call(object);
224  return object;
225 }
226 
227 } // namespace cppgc
228 
229 #endif // INCLUDE_CPPGC_ALLOCATION_H_
cppgc::internal::api_constants
Definition: api-constants.h:19
cppgc::MakeGarbageCollectedTrait::Call
static T * Call(AllocationHandle &handle, Args &&... args)
Definition: allocation.h:162
cppgc::MakeGarbageCollectedTrait::Call
static T * Call(AllocationHandle &handle, AdditionalBytes additional_bytes, Args &&... args)
Definition: allocation.h:171
cppgc::AdditionalBytes::value
const size_t value
Definition: allocation.h:145
cppgc::AdditionalBytes
Definition: allocation.h:143
cppgc::SpaceTrait
Definition: custom-space.h:69
cppgc::internal::MakeGarbageCollectedTraitInternal::Allocate
static void * Allocate(cppgc::AllocationHandle &handle, size_t size, GCInfoIndex index, CustomSpaceIndex space_index)
cppgc::MakeGarbageCollected
T * MakeGarbageCollected(AllocationHandle &handle, Args &&... args)
Definition: allocation.h:201
cppgc::MakeGarbageCollected
T * MakeGarbageCollected(AllocationHandle &handle, AdditionalBytes additional_bytes, Args &&... args)
Definition: allocation.h:219
cppgc::PostConstructionCallbackTrait
Definition: allocation.h:188
cppgc::internal::IsGarbageCollectedType
Definition: type-traits.h:104
cppgc::internal::GCInfoTrait
Definition: gc-info.h:34
cppgc::AdditionalBytes::AdditionalBytes
constexpr AdditionalBytes(size_t bytes)
Definition: allocation.h:144
cppgc
Definition: allocation.h:17
cppgc::internal::MakeGarbageCollectedTraitInternal
Definition: allocation.h:33
cppgc::internal::MakeGarbageCollectedTraitInternal::MarkObjectAsFullyConstructed
static void MarkObjectAsFullyConstructed(const void *payload)
Definition: allocation.h:35
cppgc::PostConstructionCallbackTrait::Call
static void Call(T *)
Definition: allocation.h:189
V8_EXPORT
#define V8_EXPORT
Definition: v8config.h:512
cppgc::MakeGarbageCollectedTraitBase::Allocate
static void * Allocate(AllocationHandle &handle, size_t size)
Definition: allocation.h:104
cppgc::internal::MakeGarbageCollectedTraitInternal::Allocate
static void * Allocate(cppgc::AllocationHandle &handle, size_t size, GCInfoIndex index)
cppgc::MakeGarbageCollectedTrait
Definition: allocation.h:159
cppgc::MakeGarbageCollectedTraitBase::MarkObjectAsFullyConstructed
static void MarkObjectAsFullyConstructed(const void *payload)
Definition: allocation.h:115
cppgc::CustomSpaceIndex
Definition: custom-space.h:15
cppgc::internal
Definition: allocation.h:22
cppgc::CustomSpaceBase
Definition: custom-space.h:24