v8-script.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_SCRIPT_H_
#define INCLUDE_V8_SCRIPT_H_
 
#include <stddef.h>
#include <stdint.h>
 
#include <memory>
#include <span>
#include <tuple>
#include <vector>
 
#include "v8-callbacks.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-message.h"       // NOLINT(build/include_directory)
#include "v8config.h"         // NOLINT(build/include_directory)
 
namespace v8 {
 
class Function;
class Message;
class Object;
class PrimitiveArray;
class Script;
 
namespace internal {
class BackgroundDeserializeTask;
struct ScriptStreamingData;
}  // namespace internal
 
class V8_EXPORT ScriptOrModule {
 public:
  Local<Value> GetResourceName();
 
  Local<Data> HostDefinedOptions();
};
 
class V8_EXPORT UnboundScript : public Data {
 public:
  Local<Script> BindToCurrentContext();
 
  /*
   * A unique id.
   */
  int ScriptId() const;
  V8_DEPRECATE_SOON("Use ScriptId")
  int GetId() const;
 
  Local<Value> GetScriptName();
 
  Local<Value> GetSourceURL();
  Local<Value> GetSourceMappingURL();
 
  int GetLineNumber(int code_pos = 0);
 
  int GetColumnNumber(int code_pos = 0);
 
  static const int kNoScriptId = 0;
};
 
class V8_EXPORT UnboundModuleScript : public Data {
 public:
  Local<Value> GetSourceURL();
  Local<Value> GetSourceMappingURL();
 
  /*
   * A unique id.
   */
  int ScriptId() const;
 
  static const int kNoScriptId = 0;
};
 
static_assert(UnboundModuleScript::kNoScriptId == UnboundScript::kNoScriptId);
 
class V8_EXPORT Location {
 public:
  int GetLineNumber() { return line_number_; }
  int GetColumnNumber() { return column_number_; }
 
  Location(int line_number, int column_number)
      : line_number_(line_number), column_number_(column_number) {}
 
 private:
  int line_number_;
  int column_number_;
};
 
class V8_EXPORT ModuleRequest : public Data {
 public:
  Local<String> GetSpecifier() const;
 
  ModuleImportPhase GetPhase() const;
 
  int GetSourceOffset() const;
 
  Local<FixedArray> GetImportAttributes() const;
 
  V8_DEPRECATED("Use GetImportAttributes instead")
  Local<FixedArray> GetImportAssertions() const {
    return GetImportAttributes();
  }
 
  V8_INLINE static ModuleRequest* Cast(Data* data);
 
 private:
  static void CheckCast(Data* obj);
};
 
class V8_EXPORT Module : public Data {
 public:
  enum Status {
    kUninstantiated,
    kInstantiating,
    kInstantiated,
    kEvaluating,
    kEvaluated,
    kErrored
  };
 
  Local<Value> GetResourceName() const;
 
  Status GetStatus() const;
 
  Local<Value> GetException() const;
 
  Local<FixedArray> GetModuleRequests() const;
 
  Location SourceOffsetToLocation(int offset) const;
 
  int GetIdentityHash() const;
 
  using ResolveModuleCallback = MaybeLocal<Module> (*)(
      Local<Context> context, Local<String> specifier,
      Local<FixedArray> import_attributes, Local<Module> referrer);
  using ResolveSourceCallback = MaybeLocal<Object> (*)(
      Local<Context> context, Local<String> specifier,
      Local<FixedArray> import_attributes, Local<Module> referrer);
 
  using ResolveModuleByIndexCallback = MaybeLocal<Module> (*)(
      Local<Context> context, size_t module_request_index,
      Local<Module> referrer);
  using ResolveSourceByIndexCallback = MaybeLocal<Object> (*)(
      Local<Context> context, size_t module_request_index,
      Local<Module> referrer);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> InstantiateModule(
      Local<Context> context, ResolveModuleCallback module_callback,
      ResolveSourceCallback source_callback = nullptr);
 
  V8_WARN_UNUSED_RESULT Maybe<bool> InstantiateModule(
      Local<Context> context, ResolveModuleByIndexCallback module_callback,
      ResolveSourceByIndexCallback source_callback = nullptr);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Evaluate(Local<Context> context);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Promise> EvaluateForImportDefer(
      Local<Context> context);
 
  Local<Value> GetModuleNamespace(
      v8::ModuleImportPhase phase = v8::ModuleImportPhase::kEvaluation);
 
  Local<UnboundModuleScript> GetUnboundModuleScript();
 
  int ScriptId() const;
 
  bool IsGraphAsync() const;
 
  bool HasTopLevelAwait() const;
 
  bool IsSourceTextModule() const;
 
  bool IsSyntheticModule() const;
 
  /*
   * Callback defined in the embedder.  This is responsible for setting
   * the module's exported values with calls to SetSyntheticModuleExport().
   * The callback must return a resolved Promise to indicate success (where no
   * exception was thrown) and return an empy MaybeLocal to indicate falure
   * (where an exception was thrown).
   */
  using SyntheticModuleEvaluationSteps =
      MaybeLocal<Promise> (*)(Local<Context> context, Local<Module> module);
 
  /*
   * Deprecated version of SyntheticModuleEvaluationSteps: the returned value is
   * still required to be a Promise, but that is only enforced at runtime.
   */
  // TODO(https://crbug.com/545375591): Remove once all embedders return a
  // MaybeLocal<Promise>.
  using LegacySyntheticModuleEvaluationSteps =
      MaybeLocal<Value> (*)(Local<Context> context, Local<Module> module);
 
  static Local<Module> CreateSyntheticModule(
      Isolate* isolate, Local<String> module_name,
      const std::span<const Local<String>>& export_names,
      SyntheticModuleEvaluationSteps evaluation_steps,
      Local<Data> host_defined_options = Local<Data>());
 
  // TODO(https://crbug.com/545375591): Advance to V8_DEPRECATED and then remove
  // this overload once all embedders have been migrated to the one above.
  V8_DEPRECATE_SOON(
      "Use the CreateSyntheticModule overload whose evaluation_steps return a "
      "MaybeLocal<Promise>")
  static Local<Module> CreateSyntheticModule(
      Isolate* isolate, Local<String> module_name,
      const std::span<const Local<String>>& export_names,
      LegacySyntheticModuleEvaluationSteps evaluation_steps,
      Local<Data> host_defined_options = Local<Data>());
 
  Local<Data> GetSyntheticModuleHostDefinedOptions() const;
 
  V8_WARN_UNUSED_RESULT Maybe<bool> SetSyntheticModuleExport(
      Isolate* isolate, Local<String> export_name, Local<Value> export_value);
 
  std::pair<LocalVector<Module>, LocalVector<Message>>
  GetStalledTopLevelAwaitMessages(Isolate* isolate);
 
  V8_INLINE static Module* Cast(Data* data);
 
 private:
  static void CheckCast(Data* obj);
};
 
class V8_EXPORT CompileHintsCollector : public Data {
 public:
  std::vector<int> GetCompileHints(Isolate* isolate) const;
};
 
class V8_EXPORT Script : public Data {
 public:
  static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
      Local<Context> context, Local<String> source,
      ScriptOrigin* origin = nullptr);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Run(Local<Context> context);
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Run(Local<Context> context,
                                              Local<Data> host_defined_options);
 
  Local<UnboundScript> GetUnboundScript();
 
  int ScriptId() const;
 
  Local<Value> GetResourceName();
 
  V8_DEPRECATE_SOON("Use GetCompileHintsCollector instead")
  std::vector<int> GetProducedCompileHints() const;
 
  Local<CompileHintsCollector> GetCompileHintsCollector() const;
};
 
enum class ScriptType { kClassic, kModule };
 
class V8_EXPORT ScriptCompiler {
 public:
  class ConsumeCodeCacheTask;
 
  struct V8_EXPORT CachedData {
    enum BufferPolicy { BufferNotOwned, BufferOwned };
 
    CachedData()
        : data(nullptr),
          length(0),
          rejected(false),
          buffer_policy(BufferNotOwned) {}
 
    // If buffer_policy is BufferNotOwned, the caller keeps the ownership of
    // data and guarantees that it stays alive until the CachedData object is
    // destroyed. If the policy is BufferOwned, the given data will be deleted
    // (with delete[]) when the CachedData object is destroyed.
    CachedData(const uint8_t* data, int length,
               BufferPolicy buffer_policy = BufferNotOwned);
    ~CachedData();
 
    enum CompatibilityCheckResult {
      // Don't change order/existing values of this enum since it keys into the
      // `code_cache_reject_reason` histogram. Append-only!
      kSuccess = 0,
      kMagicNumberMismatch = 1,
      kVersionMismatch = 2,
      kSourceMismatch = 3,
      kFlagsMismatch = 5,
      kChecksumMismatch = 6,
      kInvalidHeader = 7,
      kLengthMismatch = 8,
      kReadOnlySnapshotChecksumMismatch = 9,
 
      // This should always point at the last real enum value.
      kLast = kReadOnlySnapshotChecksumMismatch
    };
 
    // Check if the CachedData can be loaded in the given isolate.
    CompatibilityCheckResult CompatibilityCheck(Isolate* isolate);
 
    // TODO(marja): Async compilation; add constructors which take a callback
    // which will be called when V8 no longer needs the data.
    const uint8_t* data;
    int length;
    bool rejected;
    BufferPolicy buffer_policy;
 
    // Prevent copying.
    CachedData(const CachedData&) = delete;
    CachedData& operator=(const CachedData&) = delete;
  };
 
  enum class InMemoryCacheResult {
    // V8 did not attempt to find this script in its in-memory cache.
    kNotAttempted,
 
    // V8 found a previously compiled copy of this script in its in-memory
    // cache. Any data generated by a streaming compilation or background
    // deserialization was abandoned.
    kHit,
 
    // V8 didn't have any previously compiled data for this script.
    kMiss,
 
    // V8 had some previously compiled data for an identical script, but the
    // data was incomplete.
    kPartial,
  };
 
  // Details about what happened during a compilation.
  struct CompilationDetails {
    InMemoryCacheResult in_memory_cache_result =
        InMemoryCacheResult::kNotAttempted;
 
    static constexpr int64_t kTimeNotMeasured = -1;
    int64_t foreground_time_in_microseconds = kTimeNotMeasured;
    int64_t background_time_in_microseconds = kTimeNotMeasured;
  };
 
  class Source {
   public:
    // Source takes ownership of both CachedData and CodeCacheConsumeTask.
    // The caller *must* ensure that the cached data is from a trusted source.
    V8_INLINE Source(Local<String> source_string, const ScriptOrigin& origin,
                     CachedData* cached_data = nullptr,
                     ConsumeCodeCacheTask* consume_cache_task = nullptr);
    // Source takes ownership of both CachedData and CodeCacheConsumeTask.
    V8_INLINE explicit Source(
        Local<String> source_string, CachedData* cached_data = nullptr,
        ConsumeCodeCacheTask* consume_cache_task = nullptr);
    V8_INLINE Source(Local<String> source_string, const ScriptOrigin& origin,
                     CompileHintCallback callback, void* callback_data);
    V8_INLINE ~Source() = default;
 
    // Ownership of the CachedData or its buffers is *not* transferred to the
    // caller. The CachedData object is alive as long as the Source object is
    // alive.
    V8_INLINE const CachedData* GetCachedData() const;
 
    V8_INLINE const ScriptOriginOptions& GetResourceOptions() const;
 
    V8_INLINE const CompilationDetails& GetCompilationDetails() const;
 
   private:
    friend class ScriptCompiler;
 
    Local<String> source_string;
 
    // Origin information
    Local<Value> resource_name;
    int resource_line_offset = -1;
    int resource_column_offset = -1;
    ScriptOriginOptions resource_options;
    Local<Value> source_map_url;
    Local<Data> host_defined_options;
 
    // Cached data from previous compilation (if a kConsume*Cache flag is
    // set), or hold newly generated cache data (kProduce*Cache flags) are
    // set when calling a compile method.
    std::unique_ptr<CachedData> cached_data;
    std::unique_ptr<ConsumeCodeCacheTask> consume_cache_task;
 
    // For requesting compile hints from the embedder.
    CompileHintCallback compile_hint_callback = nullptr;
    void* compile_hint_callback_data = nullptr;
 
    // V8 writes this data and never reads it. It exists only to be informative
    // to the embedder.
    CompilationDetails compilation_details;
  };
 
  class ExternalSourceStreamBase {
   public:
    virtual ~ExternalSourceStreamBase() = default;
  };
 
  class V8_EXPORT ExternalSourceStream : public ExternalSourceStreamBase {
   public:
    ~ExternalSourceStream() override = default;
 
    virtual size_t GetMoreData(const uint8_t** src) = 0;
  };
 
  class V8_EXPORT FlexibleExternalSourceStream
      : public ExternalSourceStreamBase {
   public:
    enum class ChunkEncoding { kOneByte, kTwoByte };
 
    ~FlexibleExternalSourceStream() override = default;
 
    struct Chunk {
      Chunk(const uint8_t* data, size_t position, size_t length_in_characters,
            ChunkEncoding encoding)
          : data(data),
            position(position),
            length_in_characters(length_in_characters),
            encoding(encoding) {}
      Chunk() : Chunk(nullptr, 0, 0, ChunkEncoding::kOneByte) {}
 
      size_t end_position() const { return position + length_in_characters; }
 
      const uint8_t* data;
      size_t position;
      size_t length_in_characters;
      ChunkEncoding encoding;
    };
 
    virtual Chunk GetNextChunk() = 0;
  };
 
  class V8_EXPORT StreamedSource {
   public:
    enum Encoding { ONE_BYTE, TWO_BYTE, UTF8, WINDOWS_1252, FLEXIBLE_UTF16 };
 
    StreamedSource(std::unique_ptr<ExternalSourceStream> source_stream,
                   Encoding encoding);
    explicit StreamedSource(
        std::unique_ptr<FlexibleExternalSourceStream> source_stream);
    ~StreamedSource();
 
    internal::ScriptStreamingData* impl() const { return impl_.get(); }
 
    // Prevent copying.
    StreamedSource(const StreamedSource&) = delete;
    StreamedSource& operator=(const StreamedSource&) = delete;
 
    CompilationDetails& compilation_details() { return compilation_details_; }
 
   private:
    std::unique_ptr<internal::ScriptStreamingData> impl_;
 
    // V8 writes this data and never reads it. It exists only to be informative
    // to the embedder.
    CompilationDetails compilation_details_;
  };
 
  class V8_EXPORT ScriptStreamingTask final {
   public:
    void Run();
 
   private:
    friend class ScriptCompiler;
 
    explicit ScriptStreamingTask(internal::ScriptStreamingData* data)
        : data_(data) {}
 
    internal::ScriptStreamingData* data_;
  };
 
  class V8_EXPORT ConsumeCodeCacheTask final {
   public:
    ~ConsumeCodeCacheTask();
 
    void Run();
 
    void SourceTextAvailable(Isolate* isolate, Local<String> source_text,
                             const ScriptOrigin& origin);
 
    bool ShouldMergeWithExistingScript() const;
 
    void MergeWithExistingScript();
 
   private:
    friend class ScriptCompiler;
 
    explicit ConsumeCodeCacheTask(
        std::unique_ptr<internal::BackgroundDeserializeTask> impl);
 
    std::unique_ptr<internal::BackgroundDeserializeTask> impl_;
  };
 
  enum CompileOptions {
    kNoCompileOptions = 0,
    kConsumeCodeCache = 1 << 0,
    kEagerCompile = 1 << 1,
    kProduceCompileHints = 1 << 2,
    kConsumeCompileHints = 1 << 3,
    kFollowCompileHintsMagicComment = 1 << 4,
    kFollowCompileHintsPerFunctionMagicComment = 1 << 5,
  };
 
  static inline bool CompileOptionsIsValid(CompileOptions compile_options) {
    // kConsumeCodeCache is mutually exclusive with all other flag bits.
    if ((compile_options & kConsumeCodeCache) &&
        compile_options != kConsumeCodeCache) {
      return false;
    }
    // kEagerCompile is mutually exclusive with all other flag bits.
    if ((compile_options & kEagerCompile) && compile_options != kEagerCompile) {
      return false;
    }
    // We don't currently support producing and consuming compile hints at the
    // same time.
    constexpr int produce_and_consume = CompileOptions::kProduceCompileHints |
                                        CompileOptions::kConsumeCompileHints;
    if ((compile_options & produce_and_consume) == produce_and_consume) {
      return false;
    }
    return true;
  }
 
  enum NoCacheReason {
    kNoCacheNoReason = 0,
    kNoCacheBecauseCachingDisabled,
    kNoCacheBecauseNoResource,
    kNoCacheBecauseInlineScript,
    kNoCacheBecauseModule,
    kNoCacheBecauseStreamingSource,
    kNoCacheBecauseInspector,
    kNoCacheBecauseScriptTooSmall,
    kNoCacheBecauseCacheTooCold,
    kNoCacheBecauseV8Extension,
    kNoCacheBecauseExtensionModule,
    kNoCacheBecausePacScript,
    kNoCacheBecauseInDocumentWrite,
    kNoCacheBecauseResourceWithNoCacheHandler,
    kNoCacheBecauseDeferredProduceCodeCache,
    kNoCacheBecauseStaticCodeCache,
    kNoCacheBecauseInlineScriptCacheTooCold,
  };
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundScript(
      Isolate* isolate, Source* source,
      CompileOptions options = kNoCompileOptions,
      NoCacheReason no_cache_reason = kNoCacheNoReason);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
      Local<Context> context, Source* source,
      CompileOptions options = kNoCompileOptions,
      NoCacheReason no_cache_reason = kNoCacheNoReason);
 
  static ScriptStreamingTask* StartStreaming(
      Isolate* isolate, StreamedSource* source,
      ScriptType type = ScriptType::kClassic,
      CompileOptions options = kNoCompileOptions,
      CompileHintCallback compile_hint_callback = nullptr,
      void* compile_hint_callback_data = nullptr);
 
  static ConsumeCodeCacheTask* StartConsumingCodeCache(
      Isolate* isolate, std::unique_ptr<CachedData> source);
  static ConsumeCodeCacheTask* StartConsumingCodeCacheOnBackground(
      Isolate* isolate, std::unique_ptr<CachedData> source);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
      Local<Context> context, StreamedSource* source,
      Local<String> full_source_string, const ScriptOrigin& origin);
 
  static uint32_t CachedDataVersionTag();
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<Module> CompileModule(
      Isolate* isolate, Source* source,
      CompileOptions options = kNoCompileOptions,
      NoCacheReason no_cache_reason = kNoCacheNoReason);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<Module> CompileModule(
      Local<Context> context, StreamedSource* v8_source,
      Local<String> full_source_string, const ScriptOrigin& origin);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<Function> CompileFunction(
      Local<Context> context, Source* source, size_t arguments_count = 0,
      Local<String> arguments[] = nullptr, size_t context_extension_count = 0,
      Local<Object> context_extensions[] = nullptr,
      CompileOptions options = kNoCompileOptions,
      NoCacheReason no_cache_reason = kNoCacheNoReason);
 
  static CachedData* CreateCodeCache(Local<UnboundScript> unbound_script);
 
  static CachedData* CreateCodeCache(
      Local<UnboundModuleScript> unbound_module_script);
 
  static CachedData* CreateCodeCacheForFunction(Local<Function> function);
 
 private:
  static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundInternal(
      Isolate* isolate, Source* source, CompileOptions options,
      NoCacheReason no_cache_reason);
 
  static V8_WARN_UNUSED_RESULT MaybeLocal<Function> CompileFunctionInternal(
      Local<Context> context, Source* source, size_t arguments_count,
      Local<String> arguments[], size_t context_extension_count,
      Local<Object> context_extensions[], CompileOptions options,
      NoCacheReason no_cache_reason,
      Local<ScriptOrModule>* script_or_module_out);
};
 
ScriptCompiler::Source::Source(Local<String> string, const ScriptOrigin& origin,
                               CachedData* data,
                               ConsumeCodeCacheTask* consume_cache_task)
    : source_string(string),
      resource_name(origin.ResourceName()),
      resource_line_offset(origin.LineOffset()),
      resource_column_offset(origin.ColumnOffset()),
      resource_options(origin.Options()),
      source_map_url(origin.SourceMapUrl()),
      host_defined_options(origin.GetHostDefinedOptions()),
      cached_data(data),
      consume_cache_task(consume_cache_task) {}
 
ScriptCompiler::Source::Source(Local<String> string, CachedData* data,
                               ConsumeCodeCacheTask* consume_cache_task)
    : source_string(string),
      cached_data(data),
      consume_cache_task(consume_cache_task) {}
 
ScriptCompiler::Source::Source(Local<String> string, const ScriptOrigin& origin,
                               CompileHintCallback callback,
                               void* callback_data)
    : source_string(string),
      resource_name(origin.ResourceName()),
      resource_line_offset(origin.LineOffset()),
      resource_column_offset(origin.ColumnOffset()),
      resource_options(origin.Options()),
      source_map_url(origin.SourceMapUrl()),
      host_defined_options(origin.GetHostDefinedOptions()),
      compile_hint_callback(callback),
      compile_hint_callback_data(callback_data) {}
 
const ScriptCompiler::CachedData* ScriptCompiler::Source::GetCachedData()
    const {
  return cached_data.get();
}
 
const ScriptOriginOptions& ScriptCompiler::Source::GetResourceOptions() const {
  return resource_options;
}
 
const ScriptCompiler::CompilationDetails&
ScriptCompiler::Source::GetCompilationDetails() const {
  return compilation_details;
}
 
ModuleRequest* ModuleRequest::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<ModuleRequest*>(data);
}
 
Module* Module::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<Module*>(data);
}
 
}  // namespace v8
 
#endif  // INCLUDE_V8_SCRIPT_H_