v8  8.6.395 (node 15.0.1)
V8 is Google's open source JavaScript engine
heap.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_H_
6 #define INCLUDE_CPPGC_HEAP_H_
7 
8 #include <memory>
9 #include <vector>
10 
11 #include "cppgc/common.h"
12 #include "cppgc/custom-space.h"
13 #include "cppgc/platform.h"
14 #include "v8config.h" // NOLINT(build/include_directory)
15 
16 /**
17  * cppgc - A C++ garbage collection library.
18  */
19 namespace cppgc {
20 
21 class AllocationHandle;
22 
23 /**
24  * Implementation details of cppgc. Those details are considered internal and
25  * may change at any point in time without notice. Users should never rely on
26  * the contents of this namespace.
27  */
28 namespace internal {
29 class Heap;
30 } // namespace internal
31 
32 class V8_EXPORT Heap {
33  public:
34  /**
35  * Specifies the stack state the embedder is in.
36  */
37  using StackState = EmbedderStackState;
38 
39  /**
40  * Specifies whether conservative stack scanning is supported.
41  */
42  enum class StackSupport : uint8_t {
43  /**
44  * Conservative stack scan is supported.
45  */
47  /**
48  * Conservative stack scan is not supported. Embedders may use this option
49  * when using custom infrastructure that is unsupported by the library.
50  */
52  };
53 
54  /**
55  * Constraints for a Heap setup.
56  */
58  /**
59  * Allows the heap to grow to some initial size in bytes before triggering
60  * garbage collections. This is useful when it is known that applications
61  * need a certain minimum heap to run to avoid repeatedly invoking the
62  * garbage collector when growing the heap.
63  */
65  };
66 
67  /**
68  * Options specifying Heap properties (e.g. custom spaces) when initializing a
69  * heap through Heap::Create().
70  */
71  struct HeapOptions {
72  /**
73  * Creates reasonable defaults for instantiating a Heap.
74  *
75  * \returns the HeapOptions that can be passed to Heap::Create().
76  */
77  static HeapOptions Default() { return {}; }
78 
79  /**
80  * Custom spaces added to heap are required to have indices forming a
81  * numbered sequence starting at 0, i.e., their kSpaceIndex must correspond
82  * to the index they reside in the vector.
83  */
84  std::vector<std::unique_ptr<CustomSpaceBase>> custom_spaces;
85 
86  /**
87  * Specifies whether conserative stack scan is supported. When conservative
88  * stack scan is not supported, the collector may try to invoke
89  * garbage collections using non-nestable task, which are guaranteed to have
90  * no interesting stack, through the provided Platform. If such tasks are
91  * not supported by the Platform, the embedder must take care of invoking
92  * the GC through ForceGarbageCollectionSlow().
93  */
95 
96  /**
97  * Resource constraints specifying various properties that the internal
98  * GC scheduler follows.
99  */
101  };
102 
103  /**
104  * Creates a new heap that can be used for object allocation.
105  *
106  * \param platform implemented and provided by the embedder.
107  * \param options HeapOptions specifying various properties for the Heap.
108  * \returns a new Heap instance.
109  */
110  static std::unique_ptr<Heap> Create(
111  std::shared_ptr<Platform> platform,
113 
114  virtual ~Heap() = default;
115 
116  /**
117  * Forces garbage collection.
118  *
119  * \param source String specifying the source (or caller) triggering a
120  * forced garbage collection.
121  * \param reason String specifying the reason for the forced garbage
122  * collection.
123  * \param stack_state The embedder stack state, see StackState.
124  */
126  const char* source, const char* reason,
127  StackState stack_state = StackState::kMayContainHeapPointers);
128 
129  AllocationHandle& GetAllocationHandle();
130 
131  private:
132  Heap() = default;
133 
134  friend class internal::Heap;
135 };
136 
137 } // namespace cppgc
138 
139 #endif // INCLUDE_CPPGC_HEAP_H_