heap.h 5.55 KB
Newer Older
1 2 3 4 5 6 7 8
// 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_CPPGC_HEAP_H_
#define INCLUDE_CPPGC_HEAP_H_

#include <memory>
9
#include <vector>
10

11
#include "cppgc/common.h"
12
#include "cppgc/custom-space.h"
13
#include "cppgc/platform.h"
14
#include "v8config.h"  // NOLINT(build/include_directory)
15

16 17 18
/**
 * cppgc - A C++ garbage collection library.
 */
19
namespace cppgc {
20

21 22
class AllocationHandle;

23 24 25 26 27
/**
 * Implementation details of cppgc. Those details are considered internal and
 * may change at any point in time without notice. Users should never rely on
 * the contents of this namespace.
 */
28 29 30 31
namespace internal {
class Heap;
}  // namespace internal

32 33 34 35 36
/**
 * Used for additional heap APIs.
 */
class HeapHandle;

37 38
class V8_EXPORT Heap {
 public:
39 40 41
  /**
   * Specifies the stack state the embedder is in.
   */
42
  using StackState = EmbedderStackState;
43

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
  /**
   * Specifies whether conservative stack scanning is supported.
   */
  enum class StackSupport : uint8_t {
    /**
     * Conservative stack scan is supported.
     */
    kSupportsConservativeStackScan,
    /**
     * Conservative stack scan is not supported. Embedders may use this option
     * when using custom infrastructure that is unsupported by the library.
     */
    kNoConservativeStackScan,
  };

59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
  /**
   * Specifies supported marking types
   */
  enum class MarkingType : uint8_t {
    /**
     * Atomic stop-the-world marking. This option does not require any write
     * barriers but is the most intrusive in terms of jank.
     */
    kAtomic,
    /**
     * Incremental marking, i.e. interleave marking is the rest of the
     * application on the same thread.
     */
    kIncremental,
    /**
     * Incremental and concurrent marking.
     */
    kIncrementalAndConcurrent
  };

  /**
   * Specifies supported sweeping types
   */
  enum class SweepingType : uint8_t {
    /**
     * Atomic stop-the-world sweeping. All of sweeping is performed at once.
     */
    kAtomic,
    /**
     * Incremental and concurrent sweeping. Sweeping is split and interleaved
     * with the rest of the application.
     */
    kIncrementalAndConcurrent
  };

94 95 96 97 98 99 100 101 102 103 104 105 106
  /**
   * Constraints for a Heap setup.
   */
  struct ResourceConstraints {
    /**
     * Allows the heap to grow to some initial size in bytes before triggering
     * garbage collections. This is useful when it is known that applications
     * need a certain minimum heap to run to avoid repeatedly invoking the
     * garbage collector when growing the heap.
     */
    size_t initial_heap_size_bytes = 0;
  };

107 108
  /**
   * Options specifying Heap properties (e.g. custom spaces) when initializing a
109
   * heap through `Heap::Create()`.
110
   */
111
  struct HeapOptions {
112 113 114
    /**
     * Creates reasonable defaults for instantiating a Heap.
     *
115
     * \returns the HeapOptions that can be passed to `Heap::Create()`.
116
     */
117 118 119 120
    static HeapOptions Default() { return {}; }

    /**
     * Custom spaces added to heap are required to have indices forming a
121 122
     * numbered sequence starting at 0, i.e., their `kSpaceIndex` must
     * correspond to the index they reside in the vector.
123 124
     */
    std::vector<std::unique_ptr<CustomSpaceBase>> custom_spaces;
125 126

    /**
127
     * Specifies whether conservative stack scan is supported. When conservative
128 129 130 131
     * stack scan is not supported, the collector may try to invoke
     * garbage collections using non-nestable task, which are guaranteed to have
     * no interesting stack, through the provided Platform. If such tasks are
     * not supported by the Platform, the embedder must take care of invoking
132
     * the GC through `ForceGarbageCollectionSlow()`.
133 134 135
     */
    StackSupport stack_support = StackSupport::kSupportsConservativeStackScan;

136 137 138 139 140 141 142 143 144 145
    /**
     * Specifies which types of marking are supported by the heap.
     */
    MarkingType marking_support = MarkingType::kIncrementalAndConcurrent;

    /**
     * Specifies which types of sweeping are supported by the heap.
     */
    SweepingType sweeping_support = SweepingType::kIncrementalAndConcurrent;

146 147 148 149 150
    /**
     * Resource constraints specifying various properties that the internal
     * GC scheduler follows.
     */
    ResourceConstraints resource_constraints;
151 152
  };

153 154 155
  /**
   * Creates a new heap that can be used for object allocation.
   *
156
   * \param platform implemented and provided by the embedder.
157 158 159 160
   * \param options HeapOptions specifying various properties for the Heap.
   * \returns a new Heap instance.
   */
  static std::unique_ptr<Heap> Create(
161
      std::shared_ptr<Platform> platform,
162
      HeapOptions options = HeapOptions::Default());
163 164 165

  virtual ~Heap() = default;

166 167 168 169 170 171 172 173 174
  /**
   * 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.
   */
175 176
  void ForceGarbageCollectionSlow(
      const char* source, const char* reason,
177
      StackState stack_state = StackState::kMayContainHeapPointers);
178

179 180 181 182
  /**
   * \returns the opaque handle for allocating objects using
   * `MakeGarbageCollected()`.
   */
183 184
  AllocationHandle& GetAllocationHandle();

185 186 187 188 189 190
  /**
   * \returns the opaque heap handle which may be used to refer to this heap in
   *   other APIs. Valid as long as the underlying `Heap` is alive.
   */
  HeapHandle& GetHeapHandle();

191 192 193 194 195 196 197 198 199
 private:
  Heap() = default;

  friend class internal::Heap;
};

}  // namespace cppgc

#endif  // INCLUDE_CPPGC_HEAP_H_