chromium/v8/include/v8-traced-handle.h

// 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_TRACED_HANDLE_H_
#define INCLUDE_V8_TRACED_HANDLE_H_

#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

#include <atomic>
#include <memory>
#include <type_traits>
#include <utility>

#include "v8-internal.h"            // NOLINT(build/include_directory)
#include "v8-local-handle.h"        // NOLINT(build/include_directory)
#include "v8-weak-callback-info.h"  // NOLINT(build/include_directory)
#include "v8config.h"               // NOLINT(build/include_directory)

namespace v8 {

class Value;

namespace internal {

class BasicTracedReferenceExtractor;

enum class TracedReferenceStoreMode { … };

enum class TracedReferenceHandling { … };

V8_EXPORT Address* GlobalizeTracedReference(
    Isolate* isolate, Address value, Address* slot,
    TracedReferenceStoreMode store_mode,
    TracedReferenceHandling reference_handling);
V8_EXPORT void MoveTracedReference(Address** from, Address** to);
V8_EXPORT void CopyTracedReference(const Address* const* from, Address** to);
V8_EXPORT void DisposeTracedReference(Address* global_handle);

}  // namespace internal

/**
 * An indirect handle, where the indirect pointer points to a GlobalHandles
 * node.
 */
class TracedReferenceBase : public api_internal::IndirectHandleBase { … };

/**
 * A traced handle with copy and move semantics. The handle is to be used
 * together as part of GarbageCollected objects (see v8-cppgc.h) or from stack
 * and specifies edges from C++ objects to JavaScript.
 *
 * The exact semantics are:
 * - Tracing garbage collections using CppHeap.
 * - Non-tracing garbage collections refer to
 *   |v8::EmbedderRootsHandler::IsRoot()| whether the handle should
 * be treated as root or not.
 *
 * Note that the base class cannot be instantiated itself, use |TracedReference|
 * instead.
 */
template <typename T>
class BasicTracedReference : public TracedReferenceBase { … };

/**
 * A traced handle without destructor that clears the handle. The embedder needs
 * to ensure that the handle is not accessed once the V8 object has been
 * reclaimed. For more details see BasicTracedReference.
 */
template <typename T>
class TracedReference : public BasicTracedReference<T> { … };

// --- Implementation ---
template <class T>
internal::Address* BasicTracedReference<T>::NewFromNonEmptyValue(
    Isolate* isolate, T* that, internal::Address** slot,
    internal::TracedReferenceStoreMode store_mode,
    internal::TracedReferenceHandling reference_handling) { … }

void TracedReferenceBase::Reset() { … }

V8_INLINE bool operator==(const TracedReferenceBase& lhs,
                          const TracedReferenceBase& rhs) { … }

template <typename U>
V8_INLINE bool operator==(const TracedReferenceBase& lhs,
                          const v8::Local<U>& rhs) { … }

template <typename U>
V8_INLINE bool operator==(const v8::Local<U>& lhs,
                          const TracedReferenceBase& rhs) { … }

V8_INLINE bool operator!=(const TracedReferenceBase& lhs,
                          const TracedReferenceBase& rhs) { … }

template <typename U>
V8_INLINE bool operator!=(const TracedReferenceBase& lhs,
                          const v8::Local<U>& rhs) { … }

template <typename U>
V8_INLINE bool operator!=(const v8::Local<U>& lhs,
                          const TracedReferenceBase& rhs) { … }

template <class T>
template <class S>
void TracedReference<T>::Reset(Isolate* isolate, const Local<S>& other) { … }

template <class T>
template <class S>
void TracedReference<T>::Reset(Isolate* isolate, const Local<S>& other,
                               IsDroppable) { … }

template <class T>
template <class S>
TracedReference<T>& TracedReference<T>::operator=(
    TracedReference<S>&& rhs) noexcept { … }

template <class T>
template <class S>
TracedReference<T>& TracedReference<T>::operator=(
    const TracedReference<S>& rhs) { … }

template <class T>
TracedReference<T>& TracedReference<T>::operator=(
    TracedReference&& rhs) noexcept { … }

template <class T>
TracedReference<T>& TracedReference<T>::operator=(const TracedReference& rhs) { … }

}  // namespace v8

#endif  // INCLUDE_V8_TRACED_HANDLE_H_