cppgc: Add public garbage collection call

Adds a public method that embedders can use to trigger garbage
collections. Such garbage collections are always required to have a
source and reason specifying which components calls it why.

Change-Id: I6ae983f99227febc1b7f0dd15c191d5b1eaaf3f3
Bug: chromium:1056170
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/2181332Reviewed-by: Ulan Degenbaev <ulan@chromium.org>
Reviewed-by: Anton Bikineev <bikineev@chromium.org>
Reviewed-by: Omer Katz <omerkatz@chromium.org>
Commit-Queue: Michael Lippautz <mlippautz@chromium.org>
Cr-Commit-Position: refs/heads/master@{#67631}

include/cppgc/heap.h

@@ -38,10 +38,42 @@ class V8_EXPORT Heap {
   static constexpr size_t kMaxNumberOfSpaces =
       static_cast<size_t>(SpaceType::kUserDefined4) + 1;
 
+  /**
+   * Specifies the stack state the embedder is in.
+   */
+  enum class StackState : uint8_t {
+    /**
+     * The embedder does not know anything about it's stack.
+     */
+    kUnkown,
+    /**
+     * The stack is empty, i.e., it does not contain any raw pointers
+     * to garbage-collected objects.
+     */
+    kEmpty,
+    /**
+     * The stack is non-empty, i.e., it may contain raw pointers to
+     * garabge-collected objects.
+     */
+    kNonEmpty,
+  };
+
   static std::unique_ptr<Heap> Create();
 
   virtual ~Heap() = default;
 
+  /**
+   * Forces garbage collection.
+   *
+   * \param source String specifying the source (or caller) triggering a
+   *   forced garbage collection.
+   * \param reason String specifying the reason for the forced garbage
+   *   collection.
+   * \param stack_state The embedder stack state, see StackState.
+   */
+  void ForceGarbageCollectionSlow(const char* source, const char* reason,
+                                  StackState stack_state = StackState::kUnkown);
+
  private:
   Heap() = default;
 

src/heap/cppgc/heap.cc

@@ -20,12 +20,17 @@ std::unique_ptr<Heap> Heap::Create() {
   return std::make_unique<internal::Heap>();
 }
 
+void Heap::ForceGarbageCollectionSlow(const char* source, const char* reason,
+                                      Heap::StackState stack_state) {
+  internal::Heap::From(this)->CollectGarbage({stack_state});
+}
+
 namespace internal {
 
 namespace {
 
 constexpr bool NeedsConservativeStackScan(Heap::GCConfig config) {
-  return config.stack_state == Heap::GCConfig::StackState::kNonEmpty;
+  return config.stack_state != Heap::GCConfig::StackState::kEmpty;
 }
 
 class ObjectSizeCounter : public HeapVisitor<ObjectSizeCounter> {

src/heap/cppgc/heap.h

@@ -57,14 +57,11 @@ class V8_EXPORT_PRIVATE Heap final : public cppgc::Heap {
   };
 
   struct GCConfig {
-    enum class StackState : uint8_t {
-      kEmpty,
-      kNonEmpty,
-    };
+    using StackState = Heap::StackState;
 
-    static GCConfig Default() { return {StackState::kNonEmpty}; }
+    static GCConfig Default() { return {StackState::kUnkown}; }
 
-    StackState stack_state = StackState::kNonEmpty;
+    StackState stack_state = StackState::kUnkown;
   };
 
   static Heap* From(cppgc::Heap* heap) { return static_cast<Heap*>(heap); }

test/unittests/heap/cppgc/tests.h

@@ -28,8 +28,8 @@ class TestWithHeap : public TestWithPlatform {
   TestWithHeap();
 
   void PreciseGC() {
-    internal::Heap::From(GetHeap())->CollectGarbage(
-        {internal::Heap::GCConfig::StackState::kEmpty});
+    heap_->ForceGarbageCollectionSlow("TestWithHeap", "Testing",
+                                      Heap::StackState::kEmpty);
   }
 
   Heap* GetHeap() const { return heap_.get(); }