xref: /third_party/node/deps/v8/include/cppgc/testing.h (revision 1cb0ef41) 
1// Copyright 2021 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_TESTING_H_
6#define INCLUDE_CPPGC_TESTING_H_
7
8#include "cppgc/common.h"
9#include "cppgc/macros.h"
10#include "v8config.h"  // NOLINT(build/include_directory)
11
12namespace cppgc {
13
14class HeapHandle;
15
16/**
17 * Namespace contains testing helpers.
18 */
19namespace testing {
20
21/**
22 * Overrides the state of the stack with the provided value. Parameters passed
23 * to explicit garbage collection calls still take precedence. Must not be
24 * nested.
25 *
26 * This scope is useful to make the garbage collector consider the stack when
27 * tasks that invoke garbage collection (through the provided platform) contain
28 * interesting pointers on its stack.
29 */
30class V8_EXPORT V8_NODISCARD OverrideEmbedderStackStateScope final {
31  CPPGC_STACK_ALLOCATED();
32
33 public:
34  /**
35   * Constructs a scoped object that automatically enters and leaves the scope.
36   *
37   * \param heap_handle The corresponding heap.
38   */
39  explicit OverrideEmbedderStackStateScope(HeapHandle& heap_handle,
40                                           EmbedderStackState state);
41  ~OverrideEmbedderStackStateScope();
42
43  OverrideEmbedderStackStateScope(const OverrideEmbedderStackStateScope&) =
44      delete;
45  OverrideEmbedderStackStateScope& operator=(
46      const OverrideEmbedderStackStateScope&) = delete;
47
48 private:
49  HeapHandle& heap_handle_;
50};
51
52/**
53 * Testing interface for managed heaps that allows for controlling garbage
54 * collection timings. Embedders should use this class when testing the
55 * interaction of their code with incremental/concurrent garbage collection.
56 */
57class V8_EXPORT StandaloneTestingHeap final {
58 public:
59  explicit StandaloneTestingHeap(HeapHandle&);
60
61  /**
62   * Start an incremental garbage collection.
63   */
64  void StartGarbageCollection();
65
66  /**
67   * Perform an incremental step. This will also schedule concurrent steps if
68   * needed.
69   *
70   * \param stack_state The state of the stack during the step.
71   */
72  bool PerformMarkingStep(EmbedderStackState stack_state);
73
74  /**
75   * Finalize the current garbage collection cycle atomically.
76   * Assumes that garbage collection is in progress.
77   *
78   * \param stack_state The state of the stack for finalizing the garbage
79   * collection cycle.
80   */
81  void FinalizeGarbageCollection(EmbedderStackState stack_state);
82
83  /**
84   * Toggle main thread marking on/off. Allows to stress concurrent marking
85   * (e.g. to better detect data races).
86   *
87   * \param should_mark Denotes whether the main thread should contribute to
88   * marking. Defaults to true.
89   */
90  void ToggleMainThreadMarking(bool should_mark);
91
92  /**
93   * Force enable compaction for the next garbage collection cycle.
94   */
95  void ForceCompactionForNextGarbageCollection();
96
97 private:
98  HeapHandle& heap_handle_;
99};
100
101V8_EXPORT bool IsHeapObjectOld(void*);
102
103}  // namespace testing
104}  // namespace cppgc
105
106#endif  // INCLUDE_CPPGC_TESTING_H_
107