123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215 |
- // Copyright 2020 the V8 project authors. All rights reserved.
- // Use of this source code is governed by a BSD-style license that can be
- // found in the LICENSE file.
- #ifndef INCLUDE_V8_CPPGC_H_
- #define INCLUDE_V8_CPPGC_H_
- #include <cstdint>
- #include <memory>
- #include <vector>
- #include "cppgc/common.h"
- #include "cppgc/custom-space.h"
- #include "cppgc/heap-statistics.h"
- #include "cppgc/visitor.h"
- #include "v8-internal.h" // NOLINT(build/include_directory)
- #include "v8-platform.h" // NOLINT(build/include_directory)
- #include "v8-traced-handle.h" // NOLINT(build/include_directory)
- namespace cppgc {
- class AllocationHandle;
- class HeapHandle;
- } // namespace cppgc
- namespace v8 {
- class Object;
- namespace internal {
- class CppHeap;
- } // namespace internal
- class CustomSpaceStatisticsReceiver;
- /**
- * Describes how V8 wrapper objects maintain references to garbage-collected C++
- * objects.
- */
- struct WrapperDescriptor final {
- /**
- * The index used on `v8::Ojbect::SetAlignedPointerFromInternalField()` and
- * related APIs to add additional data to an object which is used to identify
- * JS->C++ references.
- */
- using InternalFieldIndex = int;
- /**
- * Unknown embedder id. The value is reserved for internal usages and must not
- * be used with `CppHeap`.
- */
- static constexpr uint16_t kUnknownEmbedderId = UINT16_MAX;
- constexpr WrapperDescriptor(InternalFieldIndex wrappable_type_index,
- InternalFieldIndex wrappable_instance_index,
- uint16_t embedder_id_for_garbage_collected)
- : wrappable_type_index(wrappable_type_index),
- wrappable_instance_index(wrappable_instance_index),
- embedder_id_for_garbage_collected(embedder_id_for_garbage_collected) {}
- /**
- * Index of the wrappable type.
- */
- InternalFieldIndex wrappable_type_index;
- /**
- * Index of the wrappable instance.
- */
- InternalFieldIndex wrappable_instance_index;
- /**
- * Embedder id identifying instances of garbage-collected objects. It is
- * expected that the first field of the wrappable type is a uint16_t holding
- * the id. Only references to instances of wrappables types with an id of
- * `embedder_id_for_garbage_collected` will be considered by CppHeap.
- */
- uint16_t embedder_id_for_garbage_collected;
- };
- struct V8_EXPORT CppHeapCreateParams {
- std::vector<std::unique_ptr<cppgc::CustomSpaceBase>> custom_spaces;
- WrapperDescriptor wrapper_descriptor;
- };
- /**
- * A heap for allocating managed C++ objects.
- */
- class V8_EXPORT CppHeap {
- public:
- static std::unique_ptr<CppHeap> Create(v8::Platform* platform,
- const CppHeapCreateParams& params);
- virtual ~CppHeap() = default;
- /**
- * \returns the opaque handle for allocating objects using
- * `MakeGarbageCollected()`.
- */
- cppgc::AllocationHandle& GetAllocationHandle();
- /**
- * \returns the opaque heap handle which may be used to refer to this heap in
- * other APIs. Valid as long as the underlying `CppHeap` is alive.
- */
- cppgc::HeapHandle& GetHeapHandle();
- /**
- * Terminate clears all roots and performs multiple garbage collections to
- * reclaim potentially newly created objects in destructors.
- *
- * After this call, object allocation is prohibited.
- */
- void Terminate();
- /**
- * \param detail_level specifies whether should return detailed
- * statistics or only brief summary statistics.
- * \returns current CppHeap statistics regarding memory consumption
- * and utilization.
- */
- cppgc::HeapStatistics CollectStatistics(
- cppgc::HeapStatistics::DetailLevel detail_level);
- /**
- * Collects statistics for the given spaces and reports them to the receiver.
- *
- * \param custom_spaces a collection of custom space indicies.
- * \param receiver an object that gets the results.
- */
- void CollectCustomSpaceStatisticsAtLastGC(
- std::vector<cppgc::CustomSpaceIndex> custom_spaces,
- std::unique_ptr<CustomSpaceStatisticsReceiver> receiver);
- /**
- * Enables a detached mode that allows testing garbage collection using
- * `cppgc::testing` APIs. Once used, the heap cannot be attached to an
- * `Isolate` anymore.
- */
- void EnableDetachedGarbageCollectionsForTesting();
- /**
- * Performs a stop-the-world garbage collection for testing purposes.
- *
- * \param stack_state The stack state to assume for the garbage collection.
- */
- void CollectGarbageForTesting(cppgc::EmbedderStackState stack_state);
- /**
- * Performs a stop-the-world minor garbage collection for testing purposes.
- *
- * \param stack_state The stack state to assume for the garbage collection.
- */
- void CollectGarbageInYoungGenerationForTesting(
- cppgc::EmbedderStackState stack_state);
- private:
- CppHeap() = default;
- friend class internal::CppHeap;
- };
- class JSVisitor : public cppgc::Visitor {
- public:
- explicit JSVisitor(cppgc::Visitor::Key key) : cppgc::Visitor(key) {}
- ~JSVisitor() override = default;
- void Trace(const TracedReferenceBase& ref) {
- if (ref.IsEmptyThreadSafe()) return;
- Visit(ref);
- }
- protected:
- using cppgc::Visitor::Visit;
- virtual void Visit(const TracedReferenceBase& ref) {}
- };
- /**
- * Provided as input to `CppHeap::CollectCustomSpaceStatisticsAtLastGC()`.
- *
- * Its method is invoked with the results of the statistic collection.
- */
- class CustomSpaceStatisticsReceiver {
- public:
- virtual ~CustomSpaceStatisticsReceiver() = default;
- /**
- * Reports the size of a space at the last GC. It is called for each space
- * that was requested in `CollectCustomSpaceStatisticsAtLastGC()`.
- *
- * \param space_index The index of the space.
- * \param bytes The total size of live objects in the space at the last GC.
- * It is zero if there was no GC yet.
- */
- virtual void AllocatedBytes(cppgc::CustomSpaceIndex space_index,
- size_t bytes) = 0;
- };
- } // namespace v8
- namespace cppgc {
- template <typename T>
- struct TraceTrait<v8::TracedReference<T>> {
- static cppgc::TraceDescriptor GetTraceDescriptor(const void* self) {
- return {nullptr, Trace};
- }
- static void Trace(Visitor* visitor, const void* self) {
- static_cast<v8::JSVisitor*>(visitor)->Trace(
- *static_cast<const v8::TracedReference<T>*>(self));
- }
- };
- } // namespace cppgc
- #endif // INCLUDE_V8_CPPGC_H_
|