v8-embedder-heap.h

Go to the documentation of this file.

// Copyright 2021 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_V8_EMBEDDER_HEAP_H_
#define INCLUDE_V8_EMBEDDER_HEAP_H_
 
#include <stddef.h>
#include <stdint.h>
 
#include <utility>
#include <vector>
 
#include "cppgc/common.h"
#include "v8-local-handle.h"   // NOLINT(build/include_directory)
#include "v8-traced-handle.h"  // NOLINT(build/include_directory)
#include "v8config.h"          // NOLINT(build/include_directory)
 
namespace v8 {
 
class Data;
class Isolate;
class Value;
 
namespace internal {
class LocalEmbedderHeapTracer;
}  // namespace internal
 
class V8_EXPORT EmbedderRootsHandler {
 public:
  virtual ~EmbedderRootsHandler() = default;
 
  virtual bool IsRoot(const v8::TracedReference<v8::Value>& handle) = 0;
 
  virtual void ResetRoot(const v8::TracedReference<v8::Value>& handle) = 0;
};
 
class V8_EXPORT EmbedderHeapTracer {
 public:
  using EmbedderStackState = cppgc::EmbedderStackState;
 
  enum TraceFlags : uint64_t {
    kNoFlags = 0,
    kReduceMemory = 1 << 0,
    kForced = 1 << 2,
  };
 
  class V8_EXPORT TracedGlobalHandleVisitor {
   public:
    virtual ~TracedGlobalHandleVisitor() = default;
    virtual void VisitTracedReference(const TracedReference<Value>& handle) {}
  };
 
  struct TraceSummary {
    double time = 0.0;
 
    size_t allocated_size = 0;
  };
 
  virtual ~EmbedderHeapTracer() = default;
 
  void IterateTracedGlobalHandles(TracedGlobalHandleVisitor* visitor);
 
  void SetStackStart(void* stack_start);
 
  virtual void RegisterV8References(
      const std::vector<std::pair<void*, void*>>& embedder_fields) = 0;
 
  void RegisterEmbedderReference(const BasicTracedReference<v8::Data>& ref);
 
  virtual void TracePrologue(TraceFlags flags) {}
 
  virtual bool AdvanceTracing(double deadline_in_ms) = 0;
 
  /*
   * Returns true if there no more tracing work to be done (see AdvanceTracing)
   * and false otherwise.
   */
  virtual bool IsTracingDone() = 0;
 
  virtual void TraceEpilogue(TraceSummary* trace_summary) {}
 
  virtual void EnterFinalPause(EmbedderStackState stack_state) = 0;
 
  /*
   * Called by the embedder to request immediate finalization of the currently
   * running tracing phase that has been started with TracePrologue and not
   * yet finished with TraceEpilogue.
   *
   * Will be a noop when currently not in tracing.
   *
   * This is an experimental feature.
   */
  void FinalizeTracing();
 
  virtual bool IsRootForNonTracingGC(
      const v8::TracedReference<v8::Value>& handle);
 
  virtual void ResetHandleInNonTracingGC(
      const v8::TracedReference<v8::Value>& handle);
 
  /*
   * Called by the embedder to signal newly allocated or freed memory. Not bound
   * to tracing phases. Embedders should trade off when increments are reported
   * as V8 may consult global heuristics on whether to trigger garbage
   * collection on this change.
   */
  void IncreaseAllocatedSize(size_t bytes);
  void DecreaseAllocatedSize(size_t bytes);
 
  /*
   * Returns the v8::Isolate this tracer is attached too and |nullptr| if it
   * is not attached to any v8::Isolate.
   */
  v8::Isolate* isolate() const { return isolate_; }
 
 protected:
  v8::Isolate* isolate_ = nullptr;
 
  friend class internal::LocalEmbedderHeapTracer;
};
 
}  // namespace v8
 
#endif  // INCLUDE_V8_EMBEDDER_HEAP_H_