v8
10.1.124 (node 18.2.0)
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
<
cstddef
>
9
#
include
<
cstdint
>
10
#
include
<
memory
>
11
#
include
<
vector
>
12
13
#
include
"cppgc/common.h"
14
#
include
"cppgc/custom-space.h"
15
#
include
"cppgc/platform.h"
16
#
include
"v8config.h"
// NOLINT(build/include_directory)
17
18
/**
19
* cppgc - A C++ garbage collection library.
20
*/
21
namespace
cppgc
{
22
23
class
AllocationHandle;
24
25
/**
26
* Implementation details of cppgc. Those details are considered internal and
27
* may change at any point in time without notice. Users should never rely on
28
* the contents of this namespace.
29
*/
30
namespace
internal
{
31
class
Heap;
32
}
// namespace internal
33
34
/**
35
* Used for additional heap APIs.
36
*/
37
class
HeapHandle;
38
39
class
V8_EXPORT
Heap
{
40
public
:
41
/**
42
* Specifies the stack state the embedder is in.
43
*/
44
using
StackState =
EmbedderStackState
;
45
46
/**
47
* Specifies whether conservative stack scanning is supported.
48
*/
49
enum
class
StackSupport
:
uint8_t
{
50
/**
51
* Conservative stack scan is supported.
52
*/
53
kSupportsConservativeStackScan
,
54
/**
55
* Conservative stack scan is not supported. Embedders may use this option
56
* when using custom infrastructure that is unsupported by the library.
57
*/
58
kNoConservativeStackScan
,
59
};
60
61
/**
62
* Specifies supported marking types
63
*/
64
enum
class
MarkingType
:
uint8_t
{
65
/**
66
* Atomic stop-the-world marking. This option does not require any write
67
* barriers but is the most intrusive in terms of jank.
68
*/
69
kAtomic
,
70
/**
71
* Incremental marking interleaves marking with the rest of the application
72
* workload on the same thread.
73
*/
74
kIncremental
,
75
/**
76
* Incremental and concurrent marking.
77
*/
78
kIncrementalAndConcurrent
79
};
80
81
/**
82
* Specifies supported sweeping types
83
*/
84
enum
class
SweepingType
:
uint8_t
{
85
/**
86
* Atomic stop-the-world sweeping. All of sweeping is performed at once.
87
*/
88
kAtomic
,
89
/**
90
* Incremental sweeping interleaves sweeping with the rest of the
91
* application workload on the same thread.
92
*/
93
kIncremental
,
94
/**
95
* Incremental and concurrent sweeping. Sweeping is split and interleaved
96
* with the rest of the application.
97
*/
98
kIncrementalAndConcurrent
99
};
100
101
/**
102
* Constraints for a Heap setup.
103
*/
104
struct
ResourceConstraints
{
105
/**
106
* Allows the heap to grow to some initial size in bytes before triggering
107
* garbage collections. This is useful when it is known that applications
108
* need a certain minimum heap to run to avoid repeatedly invoking the
109
* garbage collector when growing the heap.
110
*/
111
size_t
initial_heap_size_bytes
= 0;
112
};
113
114
/**
115
* Options specifying Heap properties (e.g. custom spaces) when initializing a
116
* heap through `Heap::Create()`.
117
*/
118
struct
HeapOptions
{
119
/**
120
* Creates reasonable defaults for instantiating a Heap.
121
*
122
* \returns the HeapOptions that can be passed to `Heap::Create()`.
123
*/
124
static
HeapOptions
Default
() {
return
{}; }
125
126
/**
127
* Custom spaces added to heap are required to have indices forming a
128
* numbered sequence starting at 0, i.e., their `kSpaceIndex` must
129
* correspond to the index they reside in the vector.
130
*/
131
std::vector<std::unique_ptr<
CustomSpaceBase
>>
custom_spaces
;
132
133
/**
134
* Specifies whether conservative stack scan is supported. When conservative
135
* stack scan is not supported, the collector may try to invoke
136
* garbage collections using non-nestable task, which are guaranteed to have
137
* no interesting stack, through the provided Platform. If such tasks are
138
* not supported by the Platform, the embedder must take care of invoking
139
* the GC through `ForceGarbageCollectionSlow()`.
140
*/
141
StackSupport
stack_support
=
StackSupport
::
kSupportsConservativeStackScan
;
142
143
/**
144
* Specifies which types of marking are supported by the heap.
145
*/
146
MarkingType
marking_support
=
MarkingType
::
kIncrementalAndConcurrent
;
147
148
/**
149
* Specifies which types of sweeping are supported by the heap.
150
*/
151
SweepingType
sweeping_support
=
SweepingType
::
kIncrementalAndConcurrent
;
152
153
/**
154
* Resource constraints specifying various properties that the internal
155
* GC scheduler follows.
156
*/
157
ResourceConstraints
resource_constraints
;
158
};
159
160
/**
161
* Creates a new heap that can be used for object allocation.
162
*
163
* \param platform implemented and provided by the embedder.
164
* \param options HeapOptions specifying various properties for the Heap.
165
* \returns a new Heap instance.
166
*/
167
static
std::unique_ptr<
Heap
>
Create
(
168
std::shared_ptr<
Platform
> platform,
169
HeapOptions
options =
HeapOptions
::
Default
(
)
);
170
171
virtual
~
Heap
() =
default
;
172
173
/**
174
* Forces garbage collection.
175
*
176
* \param source String specifying the source (or caller) triggering a
177
* forced garbage collection.
178
* \param reason String specifying the reason for the forced garbage
179
* collection.
180
* \param stack_state The embedder stack state, see StackState.
181
*/
182
void
ForceGarbageCollectionSlow
(
183
const
char
* source,
const
char
* reason,
184
StackState stack_state = StackState
::
kMayContainHeapPointers
);
185
186
/**
187
* \returns the opaque handle for allocating objects using
188
* `MakeGarbageCollected()`.
189
*/
190
AllocationHandle&
GetAllocationHandle
();
191
192
/**
193
* \returns the opaque heap handle which may be used to refer to this heap in
194
* other APIs. Valid as long as the underlying `Heap` is alive.
195
*/
196
HeapHandle&
GetHeapHandle
();
197
198
private
:
199
Heap() =
default
;
200
201
friend
class
internal
::Heap;
202
};
203
204
}
// namespace cppgc
205
206
#
endif
// INCLUDE_CPPGC_HEAP_H_
include
cppgc
heap.h
Generated on Tue May 24 2022 19:28:52 for v8 by
1.9.1