include/node/v8-embedder-heap.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_V8_EMBEDDER_HEAP_H_
0006 #define INCLUDE_V8_EMBEDDER_HEAP_H_
0007
0008 #include "v8-traced-handle.h"  // NOLINT(build/include_directory)
0009 #include "v8config.h"          // NOLINT(build/include_directory)
0010
0011 namespace v8 {
0012 namespace internal {
0013 class TracedHandles;
0014 }  // namespace internal
0015
0016 class Isolate;
0017 class Value;
0018
0019 /**
0020  * Handler for embedder roots on non-unified heap garbage collections.
0021  */
0022 class V8_EXPORT EmbedderRootsHandler {
0023  public:
0024   enum class RootHandling {
0025     kQueryEmbedderForNonDroppableReferences,
0026     kDontQueryEmbedderForAnyReference,
0027   };
0028
0029   virtual ~EmbedderRootsHandler() = default;
0030
0031   EmbedderRootsHandler() = default;
0032   explicit EmbedderRootsHandler(RootHandling default_traced_reference_handling)
0033       : default_traced_reference_handling_(default_traced_reference_handling) {}
0034
0035   /**
0036    * Returns true if the |TracedReference| handle should be considered as root
0037    * for the currently running non-tracing garbage collection and false
0038    * otherwise. The default implementation will keep all |TracedReference|
0039    * references as roots.
0040    *
0041    * If this returns false, then V8 may decide that the object referred to by
0042    * such a handle is reclaimed. In that case, V8 calls |ResetRoot()| for the
0043    * |TracedReference|.
0044    *
0045    * Note that the `handle` is different from the handle that the embedder holds
0046    * for retaining the object.
0047    *
0048    * The concrete implementations must be thread-safe.
0049    */
0050   virtual bool IsRoot(const v8::TracedReference<v8::Value>& handle) = 0;
0051
0052   /**
0053    * Used in combination with |IsRoot|. Called by V8 when an
0054    * object that is backed by a handle is reclaimed by a non-tracing garbage
0055    * collection. It is up to the embedder to reset the original handle.
0056    *
0057    * Note that the |handle| is different from the handle that the embedder holds
0058    * for retaining the object. It is up to the embedder to find the original
0059    * handle via the object or class id.
0060    */
0061   virtual void ResetRoot(const v8::TracedReference<v8::Value>& handle) = 0;
0062
0063   /**
0064    * Similar to |ResetRoot()|, but opportunistic. The function is called in
0065    * parallel for different handles and as such must be thread-safe. In case,
0066    * |false| is returned, |ResetRoot()| will be recalled for the same handle.
0067    */
0068   virtual bool TryResetRoot(const v8::TracedReference<v8::Value>& handle) {
0069     ResetRoot(handle);
0070     return true;
0071   }
0072
0073  private:
0074   const RootHandling default_traced_reference_handling_ =
0075       RootHandling::kQueryEmbedderForNonDroppableReferences;
0076
0077   friend class internal::TracedHandles;
0078 };
0079
0080 }  // namespace v8
0081
0082 #endif  // INCLUDE_V8_EMBEDDER_HEAP_H_