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
14namespace cppgc {
15
16class HeapHandle;
17
18namespace subtle {
19
20template <typename T>
21void FreeUnreferencedObject(HeapHandle& heap_handle, T& object);
22template <typename T>
23bool Resize(T& object, AdditionalBytes additional_bytes);
24
25}  // namespace subtle
26
27namespace internal {
28
29class 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
41namespace 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 */
60template <typename T>
61void 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 */
89template <typename T>
90bool 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