node/cppgc/testing.h

0001 // Copyright 2021 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_CPPGC_TESTING_H_
0006 #define INCLUDE_CPPGC_TESTING_H_
0007
0008 #include "cppgc/common.h"
0009 #include "cppgc/macros.h"
0010 #include "v8config.h"  // NOLINT(build/include_directory)
0011
0012 namespace cppgc {
0013
0014 class HeapHandle;
0015
0016 /**
0017  * Namespace contains testing helpers.
0018  */
0019 namespace testing {
0020
0021 /**
0022  * Overrides the state of the stack with the provided value. Parameters passed
0023  * to explicit garbage collection calls still take precedence. Must not be
0024  * nested.
0025  *
0026  * This scope is useful to make the garbage collector consider the stack when
0027  * tasks that invoke garbage collection (through the provided platform) contain
0028  * interesting pointers on its stack.
0029  */
0030 class V8_EXPORT V8_NODISCARD OverrideEmbedderStackStateScope final {
0031   CPPGC_STACK_ALLOCATED();
0032
0033  public:
0034   /**
0035    * Constructs a scoped object that automatically enters and leaves the scope.
0036    *
0037    * \param heap_handle The corresponding heap.
0038    */
0039   explicit OverrideEmbedderStackStateScope(HeapHandle& heap_handle,
0040                                            EmbedderStackState state);
0041   ~OverrideEmbedderStackStateScope();
0042
0043   OverrideEmbedderStackStateScope(const OverrideEmbedderStackStateScope&) =
0044       delete;
0045   OverrideEmbedderStackStateScope& operator=(
0046       const OverrideEmbedderStackStateScope&) = delete;
0047
0048  private:
0049   HeapHandle& heap_handle_;
0050 };
0051
0052 /**
0053  * Testing interface for managed heaps that allows for controlling garbage
0054  * collection timings. Embedders should use this class when testing the
0055  * interaction of their code with incremental/concurrent garbage collection.
0056  */
0057 class V8_EXPORT StandaloneTestingHeap final {
0058  public:
0059   explicit StandaloneTestingHeap(HeapHandle&);
0060
0061   /**
0062    * Start an incremental garbage collection.
0063    */
0064   void StartGarbageCollection();
0065
0066   /**
0067    * Perform an incremental step. This will also schedule concurrent steps if
0068    * needed.
0069    *
0070    * \param stack_state The state of the stack during the step.
0071    */
0072   bool PerformMarkingStep(EmbedderStackState stack_state);
0073
0074   /**
0075    * Finalize the current garbage collection cycle atomically.
0076    * Assumes that garbage collection is in progress.
0077    *
0078    * \param stack_state The state of the stack for finalizing the garbage
0079    * collection cycle.
0080    */
0081   void FinalizeGarbageCollection(EmbedderStackState stack_state);
0082
0083   /**
0084    * Toggle main thread marking on/off. Allows to stress concurrent marking
0085    * (e.g. to better detect data races).
0086    *
0087    * \param should_mark Denotes whether the main thread should contribute to
0088    * marking. Defaults to true.
0089    */
0090   void ToggleMainThreadMarking(bool should_mark);
0091
0092   /**
0093    * Force enable compaction for the next garbage collection cycle.
0094    */
0095   void ForceCompactionForNextGarbageCollection();
0096
0097  private:
0098   HeapHandle& heap_handle_;
0099 };
0100
0101 V8_EXPORT bool IsHeapObjectOld(void*);
0102
0103 }  // namespace testing
0104 }  // namespace cppgc
0105
0106 #endif  // INCLUDE_CPPGC_TESTING_H_