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_V8_EMBEDDER_HEAP_H_
6#define INCLUDE_V8_EMBEDDER_HEAP_H_
7
8#include "v8-traced-handle.h"  // NOLINT(build/include_directory)
9#include "v8config.h"          // NOLINT(build/include_directory)
10
11namespace v8 {
12
13class Isolate;
14class Value;
15
16/**
17 * Handler for embedder roots on non-unified heap garbage collections.
18 */
19class V8_EXPORT EmbedderRootsHandler {
20 public:
21  virtual ~EmbedderRootsHandler() = default;
22
23  /**
24   * Returns true if the |TracedReference| handle should be considered as root
25   * for the currently running non-tracing garbage collection and false
26   * otherwise. The default implementation will keep all |TracedReference|
27   * references as roots.
28   *
29   * If this returns false, then V8 may decide that the object referred to by
30   * such a handle is reclaimed. In that case, V8 calls |ResetRoot()| for the
31   * |TracedReference|.
32   *
33   * Note that the `handle` is different from the handle that the embedder holds
34   * for retaining the object. The embedder may use |WrapperClassId()| to
35   * distinguish cases where it wants handles to be treated as roots from not
36   * being treated as roots.
37   *
38   * The concrete implementations must be thread-safe.
39   */
40  virtual bool IsRoot(const v8::TracedReference<v8::Value>& handle) = 0;
41
42  /**
43   * Used in combination with |IsRoot|. Called by V8 when an
44   * object that is backed by a handle is reclaimed by a non-tracing garbage
45   * collection. It is up to the embedder to reset the original handle.
46   *
47   * Note that the |handle| is different from the handle that the embedder holds
48   * for retaining the object. It is up to the embedder to find the original
49   * handle via the object or class id.
50   *
51   * The concrete implementations must be thread-safe.
52   */
53  virtual void ResetRoot(const v8::TracedReference<v8::Value>& handle) = 0;
54};
55
56}  // namespace v8
57
58#endif  // INCLUDE_V8_EMBEDDER_HEAP_H_
59