Skip to content

V
V8
Commit 2e61c41c authored by Michael Lippautz's avatar Michael Lippautz Committed by Commit Bot
Browse files
Options

cppgc: First round of API docs 

Bug: chromium:1056170
Change-Id: Idbbab7af430e3bc2791eba630b331a75a67e35a9
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/2142262Reviewed-by: 's avatarAnton Bikineev <bikineev@chromium.org>
Reviewed-by: 's avatarOmer Katz <omerkatz@chromium.org>
Commit-Queue: Michael Lippautz <mlippautz@chromium.org>
Cr-Commit-Position: refs/heads/master@{#67112}
parent bb9f0c2b
Hide whitespace changes
Inline Side-by-side
Showing with 161 additions and 48 deletions
include/cppgc/allocation.h
View file @ 2e61c41c
......@@ -41,30 +41,53 @@ class V8_EXPORT MakeGarbageCollectedTraitInternal {
} // namespace internal
// Users with custom allocation needs (e.g. overriding size) should override
// MakeGarbageCollectedTrait (see below) and inherit their trait from
// MakeGarbageCollectedTraitBase to get access to low-level primitives.
/**
* Base trait that provides utilities for advancers users that have custom
* allocation needs (e.g., overriding size). It's expected that users override
* MakeGarbageCollectedTrait (see below) and inherit from
* MakeGarbageCollectedTraitBase and make use of the low-level primitives
* offered to allocate and construct an object.
*/
template <typename T>
class MakeGarbageCollectedTraitBase
: private internal::MakeGarbageCollectedTraitInternal {
protected:
// Allocates an object of |size| bytes on |heap|.
//
// TODO(mlippautz): Allow specifying arena for specific embedder uses.
/**
* Allocates memory for an object of type T.
*
* \param heap The heap to allocate this object on.
* \param size The size that should be reserved for the object.
* \returns the memory to construct an object of type T on.
*/
static void* Allocate(Heap* heap, size_t size) {
// TODO(chromium:1056170): Allow specifying arena for specific embedder
// uses.
return internal::MakeGarbageCollectedTraitInternal::Allocate(
heap, size, internal::GCInfoTrait<T>::Index());
}
// Marks an object as being fully constructed, resulting in precise handling
// by the garbage collector.
/**
* Marks an object as fully constructed, resulting in precise handling by the
* garbage collector.
*
* \param payload The base pointer the object is allocated at.
*/
static void MarkObjectAsFullyConstructed(const void* payload) {
// internal::MarkObjectAsFullyConstructed(payload);
internal::MakeGarbageCollectedTraitInternal::MarkObjectAsFullyConstructed(
payload);
}
};
/**
* Default trait class that specifies how to construct an object of type T.
* Advanced users may override how an object is constructed using the utilities
* that are provided through MakeGarbageCollectedTraitBase.
*
* Any trait overriding construction must
* - allocate through MakeGarbageCollectedTraitBase<T>::Allocate;
* - mark the object as fully constructed using
* MakeGarbageCollectedTraitBase<T>::MarkObjectAsFullyConstructed;
*/
template <typename T>
class MakeGarbageCollectedTrait : public MakeGarbageCollectedTraitBase<T> {
public:
......@@ -83,8 +106,14 @@ class MakeGarbageCollectedTrait : public MakeGarbageCollectedTraitBase<T> {
}
};
// Default MakeGarbageCollected: Constructs an instance of T, which is a garbage
// collected type.
/**
* Constructs a managed object of type T where T transitively inherits from
* GarbageCollected.
*
* \param args List of arguments with which an instance of T will be
* constructed.
* \returns an instance of type T.
*/
template <typename T, typename... Args>
T* MakeGarbageCollected(Heap* heap, Args&&... args) {
return MakeGarbageCollectedTrait<T>::Call(heap, std::forward<Args>(args)...);
......
include/cppgc/garbage-collected.h
View file @ 2e61c41c
......@@ -38,6 +38,41 @@ class GarbageCollectedBase {
} // namespace internal
/**
* Base class for managed objects. Only descendent types of GarbageCollected can
* be constructed using MakeGarbageCollected. Must be inherited from as
* left-most base class.
*
* Types inheriting from GarbageCollected must provide a method of
* signature `void Trace(cppgc::Visitor*)` that dispatchs all managed pointers
* to the visitor and delegates to garbage-collected base classes. The method
* must be virtual if the type is not directly a child of GarbageCollected and
* marked as final.
*
* \code
* // Example using final class.
* class FinalType final : public GarbageCollected<FinalType> {
* public:
* void Trace(cppgc::Visitor* visitor) {
* // Dispatch using visitor->Trace(...);
* }
* };
*
* // Example using non-final base class.
* class NonFinalBase : public GarbageCollected<NonFinalBase> {
* public:
* virtual void Trace(cppgc::Visitor*) {}
* };
*
* class FinalChild final : public NonFinalBase {
* public:
* void Trace(cppgc::Visitor* visitor) final {
* // Dispatch using visitor->Trace(...);
* NonFinalBase::Trace(visitor);
* }
* };
* \endcode
*/
template <typename>
class GarbageCollected : public internal::GarbageCollectedBase {
public:
......@@ -47,6 +82,24 @@ class GarbageCollected : public internal::GarbageCollectedBase {
GarbageCollected() = default;
};
/**
* Base class for managed mixin objects. Such objects cannot be constructed
* directly but must be mixed into the inheritance hierarchy of a
* GarbageCollected object.
*
* Types inheriting from GarbageCollectedMixin must override a virtual method of
* signature `void Trace(cppgc::Visitor*)` that dispatchs all managed pointers
* to the visitor and delegates to base classes.
*
* \code
* class Mixin : public GarbageCollectedMixin {
* public:
* void Trace(cppgc::Visitor* visitor) override {
* // Dispatch using visitor->Trace(...);
* }
* };
* \endcode
*/
class GarbageCollectedMixin : public internal::GarbageCollectedBase {
public:
using IsGarbageCollectedMixinTypeMarker = void;
......@@ -54,14 +107,18 @@ class GarbageCollectedMixin : public internal::GarbageCollectedBase {
// Sentinel used to mark not-fully-constructed mixins.
static constexpr void* kNotFullyConstructedObject = nullptr;
virtual void Trace(cppgc::Visitor*) {}
// Provide default implementation that indicate that the vtable is not yet
// set up properly. This is used to to get GCInfo objects for mixins so that
// these objects can be processed later on.
virtual TraceDescriptor GetTraceDescriptor() const {
return {kNotFullyConstructedObject, nullptr};
}
/**
* This Trace method must be overriden by objects inheriting from
* GarbageCollectedMixin.
*/
virtual void Trace(cppgc::Visitor*) {}
};
namespace internal {
......@@ -70,12 +127,32 @@ class __thisIsHereToForceASemicolonAfterThisMacro {};
} // namespace internal
// The USING_GARBAGE_COLLECTED_MIXIN macro defines all methods and markers
// needed for handling mixins. HasUsingGarbageCollectedMixinMacro is used
// by the clang GC plugin to check for proper usages of the
// USING_GARBAGE_COLLECTED_MIXIN macro.
/**
* Macro defines all methods and markers needed for handling mixins. Must be
* used on the type that is inheriting from GarbageCollected *and*
* GarbageCollectedMixin.
*
* \code
* class Mixin : public GarbageCollectedMixin {
* public:
* void Trace(cppgc::Visitor* visitor) override {
* // Dispatch using visitor->Trace(...);
* }
* };
*
* class Foo : public GarbageCollected<Foo>, public Mixin {
* USING_GARBAGE_COLLECTED_MIXIN();
* public:
* void Trace(cppgc::Visitor* visitor) override {
* // Dispatch using visitor->Trace(...);
* Mixin::Trace(visitor);
* }
* };
* \endcode
*/
#define USING_GARBAGE_COLLECTED_MIXIN() \
public: \
/* Marker is used by clang to check for proper usages of the macro. */ \
typedef int HasUsingGarbageCollectedMixinMacro; \
\
TraceDescriptor GetTraceDescriptor() const override { \
......@@ -91,23 +168,23 @@ class __thisIsHereToForceASemicolonAfterThisMacro {};
private: \
friend class internal::__thisIsHereToForceASemicolonAfterThisMacro
// Merge two or more Mixins into one:
//
// class A : public GarbageCollectedMixin {};
// class B : public GarbageCollectedMixin {};
// class C : public A, public B {
// // C::GetTraceDescriptor is now ambiguous because there are two
// // candidates: A::GetTraceDescriptor and B::GetTraceDescriptor. Ditto for
// // other functions.
//
// MERGE_GARBAGE_COLLECTED_MIXINS();
// // The macro defines C::GetTraceDescriptor, similar to
// // GarbageCollectedMixin, so that they are no longer ambiguous.
// // USING_GARBAGE_COLLECTED_MIXIN() overrides them later and provides the
// // implementations.
// };
/**
* Merge two or more Mixins into one.
*
* \code
* class A : public GarbageCollectedMixin {};
* class B : public GarbageCollectedMixin {};
* class C : public A, public B {
* MERGE_GARBAGE_COLLECTED_MIXINS();
* public:
* };
* \endcode
*/
#define MERGE_GARBAGE_COLLECTED_MIXINS() \
public: \
/* When using multiple mixins the methods become */ \
/* ambigous. Providing additional implementations */ \
/* disambiguate them again. */ \
TraceDescriptor GetTraceDescriptor() const override { \
return {kNotFullyConstructedObject, nullptr}; \
} \
......
include/cppgc/member.h
View file @ 2e61c41c
......@@ -37,8 +37,9 @@ class BasicMember : private CheckingPolicy {
template <typename U, typename OtherBarrierPolicy, typename OtherWeaknessTag,
typename OtherCheckingPolicy,
typename = std::enable_if_t<std::is_base_of<T, U>::value>>
BasicMember(const BasicMember<U, OtherWeaknessTag, OtherBarrierPolicy,
OtherCheckingPolicy>& other)
BasicMember( // NOLINT
const BasicMember<U, OtherWeaknessTag, OtherBarrierPolicy,
OtherCheckingPolicy>& other)
: BasicMember(other.Get()) {}
BasicMember& operator=(const BasicMember& other) {
......@@ -78,7 +79,7 @@ class BasicMember : private CheckingPolicy {
}
explicit operator bool() const { return Get(); }
operator T*() const { return Get(); }
operator T*() const { return Get(); } // NOLINT
T* operator->() const { return Get(); }
T& operator*() const { return *Get(); }
......@@ -146,27 +147,33 @@ struct IsWeak<
} // namespace internal
// Members are used in classes to contain strong pointers to other garbage
// collected objects. All Member fields of a class must be traced in the class'
// trace method.
/**
* Members are used in classes to contain strong pointers to other garbage
* collected objects. All Member fields of a class must be traced in the class'
* trace method.
*/
template <typename T>
using Member = internal::BasicMember<T, internal::StrongMemberTag,
internal::DijkstraWriteBarrierPolicy>;
// WeakMember is similar to Member in that it is used to point to other garbage
// collected objects. However instead of creating a strong pointer to the
// object, the WeakMember creates a weak pointer, which does not keep the
// pointee alive. Hence if all pointers to to a heap allocated object are weak
// the object will be garbage collected. At the time of GC the weak pointers
// will automatically be set to null.
/**
* WeakMember is similar to Member in that it is used to point to other garbage
* collected objects. However instead of creating a strong pointer to the
* object, the WeakMember creates a weak pointer, which does not keep the
* pointee alive. Hence if all pointers to to a heap allocated object are weak
* the object will be garbage collected. At the time of GC the weak pointers
* will automatically be set to null.
*/
template <typename T>
using WeakMember = internal::BasicMember<T, internal::WeakMemberTag,
internal::DijkstraWriteBarrierPolicy>;
// UntracedMember is a pointer to an on-heap object that is not traced for some
// reason. Do not use this unless you know what you are doing. Keeping raw
// pointers to on-heap objects is prohibited unless used from stack. Pointee
// must be kept alive through other means.
/**
* UntracedMember is a pointer to an on-heap object that is not traced for some
* reason. Do not use this unless you know what you are doing. Keeping raw
* pointers to on-heap objects is prohibited unless used from stack. Pointee
* must be kept alive through other means.
*/
template <typename T>
using UntracedMember = internal::BasicMember<T, internal::UntracedMemberTag,
internal::NoWriteBarrierPolicy>;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment