v8-context.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_CONTEXT_H_
#define INCLUDE_V8_CONTEXT_H_
 
#include <stdint.h>
 
#include <type_traits>
#include <vector>
 
#include "cppgc/type-traits.h"  // NOLINT(build/include_directory)
#include "v8-data.h"            // NOLINT(build/include_directory)
#include "v8-local-handle.h"    // NOLINT(build/include_directory)
#include "v8-maybe.h"           // NOLINT(build/include_directory)
#include "v8-snapshot.h"        // NOLINT(build/include_directory)
#include "v8config.h"           // NOLINT(build/include_directory)
 
namespace v8 {
 
class Function;
class MicrotaskQueue;
class Object;
class ObjectTemplate;
class Value;
class String;
 
#ifndef V8_EMBEDDER_DATA_ARRAY_SIZE
// Defined using gn arg `v8_embedder_data_array_size`.
#define V8_EMBEDDER_DATA_ARRAY_SIZE 5
#endif
 
class V8_EXPORT ExtensionConfiguration {
 public:
  ExtensionConfiguration() : name_count_(0), names_(nullptr) {}
  ExtensionConfiguration(int name_count, const char* names[])
      : name_count_(name_count), names_(names) {}
 
  const char** begin() const { return &names_[0]; }
  const char** end() const { return &names_[name_count_]; }
 
 private:
  const int name_count_;
  const char** names_;
};
 
class V8_EXPORT Context : public Data {
 public:
  Local<Object> Global();
 
  void DetachGlobal();
 
  static Local<Context> New(
      Isolate* isolate, ExtensionConfiguration* extensions = nullptr,
      MaybeLocal<ObjectTemplate> global_template = MaybeLocal<ObjectTemplate>(),
      MaybeLocal<Value> global_object = MaybeLocal<Value>(),
      DeserializeInternalFieldsCallback internal_fields_deserializer =
          DeserializeInternalFieldsCallback(),
      MicrotaskQueue* microtask_queue = nullptr,
      DeserializeContextDataCallback context_data_deserializer =
          DeserializeContextDataCallback(),
      DeserializeAPIWrapperCallback api_wrapper_deserializer =
          DeserializeAPIWrapperCallback());
 
  static MaybeLocal<Context> FromSnapshot(
      Isolate* isolate, size_t context_snapshot_index,
      DeserializeInternalFieldsCallback internal_fields_deserializer =
          DeserializeInternalFieldsCallback(),
      ExtensionConfiguration* extensions = nullptr,
      MaybeLocal<Value> global_object = MaybeLocal<Value>(),
      MicrotaskQueue* microtask_queue = nullptr,
      DeserializeContextDataCallback context_data_deserializer =
          DeserializeContextDataCallback(),
      DeserializeAPIWrapperCallback api_wrapper_deserializer =
          DeserializeAPIWrapperCallback());
 
  static MaybeLocal<Object> NewRemoteContext(
      Isolate* isolate, Local<ObjectTemplate> global_template,
      MaybeLocal<Value> global_object = MaybeLocal<Value>());
 
  void SetSecurityToken(Local<Value> token);
 
  void UseDefaultSecurityToken();
 
  Local<Value> GetSecurityToken();
 
  void Enter();
 
  void Exit();
 
  class DeepFreezeDelegate {
   public:
    virtual bool FreezeEmbedderObjectAndGetChildren(
        Local<Object> obj, LocalVector<Object>& children_out) = 0;
  };
 
  Maybe<void> DeepFreeze(DeepFreezeDelegate* delegate = nullptr);
 
  MicrotaskQueue* GetMicrotaskQueue();
 
  void SetMicrotaskQueue(MicrotaskQueue* queue);
 
  enum EmbedderDataFields { kDebugIdIndex = 0 };
 
  uint32_t GetNumberOfEmbedderDataFields();
 
  V8_INLINE Local<Data> GetEmbedderDataV2(int index);
 
  V8_DEPRECATED("Use SetEmbedderDataV3 instead")
  void SetEmbedderDataV2(int index, Local<Data> value);
 
  void SetEmbedderDataV3(int index, Local<Data> value);
 
  V8_DEPRECATE_SOON("Use GetEmbedderDataV2 instead")
  V8_INLINE Local<Value> GetEmbedderData(int index);
 
  Local<Object> GetExtrasBindingObject();
 
  V8_DEPRECATED("Use SetEmbedderDataV3 instead")
  void SetEmbedderData(int index, Local<Value> value);
 
  V8_INLINE void* GetAlignedPointerFromEmbedderData(Isolate* isolate, int index,
                                                    EmbedderDataTypeTag tag);
  void* GetAlignedPointerFromEmbedderData(int index,
                                          EmbedderDataTypeTag tag);
  template <typename T>
    requires cppgc::IsGarbageCollectedTypeV<T>
  V8_INLINE T* GetAlignedPointerFromEmbedderData(Isolate* isolate, int index,
                                                 CppHeapPointerTag tag);
 
  V8_DEPRECATED("Use SetAlignedPointerInEmbedderDataV2 instead")
  void SetAlignedPointerInEmbedderData(int index, void* value,
                                       EmbedderDataTypeTag tag);
 
  template <typename T>
    requires(!std::is_void_v<T>) && cppgc::IsGarbageCollectedTypeV<T>
  V8_DEPRECATED("Use SetAlignedPointerInEmbedderDataV2 instead")
  void SetAlignedPointerInEmbedderData(int index, T* value,
                                       CppHeapPointerTag tag) {
    SetAlignedPointerInEmbedderDataInternal(index, static_cast<void*>(value),
                                            tag);
  }
 
  void SetAlignedPointerInEmbedderDataV2(int index, void* value,
                                         EmbedderDataTypeTag tag);
 
  template <typename T>
    requires(!std::is_void_v<T>) && cppgc::IsGarbageCollectedTypeV<T>
  void SetAlignedPointerInEmbedderDataV2(int index, T* value,
                                         CppHeapPointerTag tag) {
    SetAlignedPointerInEmbedderDataInternalV2(index, static_cast<void*>(value),
                                              tag);
  }
 
  void AllowCodeGenerationFromStrings(bool allow);
 
  bool IsCodeGenerationFromStringsAllowed() const;
 
  void SetErrorMessageForCodeGenerationFromStrings(Local<String> message);
 
  void SetErrorMessageForWasmCodeGeneration(Local<String> message);
 
  template <class T>
  V8_INLINE MaybeLocal<T> GetDataFromSnapshotOnce(size_t index);
 
  using AbortScriptExecutionCallback = void (*)(Isolate* isolate,
                                                Local<Context> context);
  void SetAbortScriptExecution(AbortScriptExecutionCallback callback);
 
  using TemporalHostSystemUTCEpochNanosecondsCallback =
      int64_t (*)(Local<Context> context);
  void SetTemporalHostSystemUTCEpochNanosecondsCallback(
      TemporalHostSystemUTCEpochNanosecondsCallback callback);
 
  void SetPromiseHooks(Local<Function> init_hook, Local<Function> before_hook,
                       Local<Function> after_hook,
                       Local<Function> resolve_hook);
 
  bool HasTemplateLiteralObject(Local<Value> object);
  class V8_NODISCARD Scope {
   public:
    explicit V8_INLINE Scope(Local<Context> context) : context_(context) {
      context_->Enter();
    }
    V8_INLINE ~Scope() { context_->Exit(); }
 
   private:
    Local<Context> context_;
  };
 
  class V8_EXPORT V8_NODISCARD BackupIncumbentScope final {
   public:
    explicit BackupIncumbentScope(Local<Context> backup_incumbent_context);
    ~BackupIncumbentScope();
 
   private:
    friend class internal::Isolate;
 
    uintptr_t JSStackComparableAddressPrivate() const {
      return js_stack_comparable_address_;
    }
 
    Local<Context> backup_incumbent_context_;
    uintptr_t js_stack_comparable_address_ = 0;
    const BackupIncumbentScope* prev_ = nullptr;
  };
 
  V8_INLINE static Context* Cast(Data* data);
 
 private:
  friend class Value;
  friend class Script;
  friend class Object;
  friend class Function;
 
  static void CheckCast(Data* obj);
 
  internal::ValueHelper::InternalRepresentationType GetDataFromSnapshotOnce(
      size_t index);
  Local<Value> SlowGetEmbedderData(int index);
  Local<Data> SlowGetEmbedderDataV2(int index);
  void* SlowGetAlignedPointerFromEmbedderData(int index, CppHeapPointerTag tag);
  void SetAlignedPointerInEmbedderDataInternal(int index, void* value,
                                               CppHeapPointerTag tag);
  void SetAlignedPointerInEmbedderDataInternalV2(int index, void* value,
                                                 CppHeapPointerTag tag);
};
 
// --- Implementation ---
 
Local<Value> Context::GetEmbedderData(int index) {
#ifndef V8_ENABLE_CHECKS
  using A = internal::Address;
  using I = internal::Internals;
  A ctx = internal::ValueHelper::ValueAsAddress(this);
  A embedder_data =
      I::ReadTaggedPointerField(ctx, I::kNativeContextEmbedderDataOffset);
  int value_offset =
      I::kEmbedderDataArrayHeaderSize + (I::kEmbedderDataSlotSize * index);
#ifdef V8_COMPRESS_POINTERS
  // The tagged payload lives in the low kTaggedSize half of the slot (at
  // kTaggedPayloadOffset == 0). Read it as a 32-bit field so the correct half
  // is picked on both little and big endian targets. A full width read plus
  // truncation would return the CppHeap pointer half on big endian.
  uint32_t compressed = I::ReadRawField<uint32_t>(embedder_data, value_offset);
  A value = I::DecompressTaggedField(embedder_data, compressed);
#else
  A value = I::ReadRawField<A>(embedder_data, value_offset);
#endif
 
  auto* isolate = I::GetCurrentIsolate();
  return Local<Value>::New(isolate, value);
#else
  return SlowGetEmbedderData(index);
#endif
}
 
V8_INLINE Local<Data> Context::GetEmbedderDataV2(int index) {
#ifndef V8_ENABLE_CHECKS
  using A = internal::Address;
  using I = internal::Internals;
  A ctx = internal::ValueHelper::ValueAsAddress(this);
  A embedder_data =
      I::ReadTaggedPointerField(ctx, I::kNativeContextEmbedderDataOffset);
  int value_offset =
      I::kEmbedderDataArrayHeaderSize + (I::kEmbedderDataSlotSize * index);
#ifdef V8_COMPRESS_POINTERS
  // The tagged payload lives in the low kTaggedSize half of the slot (at
  // kTaggedPayloadOffset == 0). Read it as a 32-bit field so the correct half
  // is picked on both little and big endian targets. A full-width read plus
  // truncation would return the CppHeap pointer half on big endian.
  uint32_t compressed = I::ReadRawField<uint32_t>(embedder_data, value_offset);
  A value = I::DecompressTaggedField(embedder_data, compressed);
#else
  A value = I::ReadRawField<A>(embedder_data, value_offset);
#endif
 
  auto* isolate = I::GetCurrentIsolate();
  return Local<Data>::New(isolate, value);
#else
  return SlowGetEmbedderDataV2(index);
#endif
}
 
V8_INLINE void* Context::GetAlignedPointerFromEmbedderData(
    Isolate* isolate, int index, EmbedderDataTypeTag tag) {
  return GetAlignedPointerFromEmbedderData(index, tag);
}
 
template <typename T>
  requires cppgc::IsGarbageCollectedTypeV<T>
T* Context::GetAlignedPointerFromEmbedderData(Isolate* isolate, int index,
                                              CppHeapPointerTag tag) {
#if !defined(V8_ENABLE_CHECKS)
  using A = internal::Address;
  using I = internal::Internals;
  A ctx = internal::ValueHelper::ValueAsAddress(this);
  A embedder_data =
      I::ReadTaggedPointerField(ctx, I::kNativeContextEmbedderDataOffset);
  int value_offset = I::kEmbedderDataArrayHeaderSize +
                     (I::kEmbedderDataSlotSize * index) +
                     I::kEmbedderDataSlotCppHeapPointerOffset;
  return internal::ReadCppHeapPointerField<T>(
      isolate, embedder_data, value_offset, CppHeapPointerTagRange(tag, tag));
#else
  return static_cast<T*>(SlowGetAlignedPointerFromEmbedderData(index, tag));
#endif
}
 
template <class T>
MaybeLocal<T> Context::GetDataFromSnapshotOnce(size_t index) {
  if (auto repr = GetDataFromSnapshotOnce(index);
      repr != internal::ValueHelper::kEmpty) {
    internal::PerformCastCheck(internal::ValueHelper::ReprAsValue<T>(repr));
    return Local<T>::FromRepr(repr);
  }
  return {};
}
 
Context* Context::Cast(v8::Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return static_cast<Context*>(data);
}
 
}  // namespace v8
 
#endif  // INCLUDE_V8_CONTEXT_H_