v8-wasm.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_WASM_H_
#define INCLUDE_V8_WASM_H_
 
#include <functional>
#include <memory>
#include <span>
#include <string>
#include <string_view>
#include <variant>
 
#include "v8-internal.h"      // NOLINT(build/include_directory)
#include "v8-local-handle.h"  // NOLINT(build/include_directory)
#include "v8-object.h"        // NOLINT(build/include_directory)
#include "v8-platform.h"      // NOLINT(build/include_directory)
#include "v8config.h"         // NOLINT(build/include_directory)
 
namespace v8 {
 
class ArrayBuffer;
class Promise;
 
namespace internal::wasm {
class NativeModule;
}  // namespace internal::wasm
 
struct OwnedBuffer {
  std::unique_ptr<const uint8_t[]> buffer;
  size_t size = 0;
  OwnedBuffer(std::unique_ptr<const uint8_t[]> buffer, size_t size)
      : buffer(std::move(buffer)), size(size) {}
  OwnedBuffer() = default;
};
 
class V8_EXPORT CompiledWasmModule {
 public:
  OwnedBuffer Serialize();
 
  std::span<const uint8_t> GetWireBytesRef();
 
  const std::string& source_url() const { return source_url_; }
 
 private:
  friend class WasmModuleCompilation;
  friend class WasmModuleObject;
  friend class WasmStreaming;
 
  explicit CompiledWasmModule(std::shared_ptr<internal::wasm::NativeModule>,
                              std::string source_url);
 
  const std::shared_ptr<internal::wasm::NativeModule> native_module_;
  const std::string source_url_;
};
 
// An instance of WebAssembly.Memory.
class V8_EXPORT WasmMemoryObject : public Object {
 public:
  WasmMemoryObject() = delete;
 
  Local<ArrayBuffer> Buffer();
 
  V8_INLINE static WasmMemoryObject* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(value);
#endif
    return static_cast<WasmMemoryObject*>(value);
  }
 
 private:
  static void CheckCast(Value* object);
};
 
// An instance of WebAssembly.Module.
class V8_EXPORT WasmModuleObject : public Object {
 public:
  WasmModuleObject() = delete;
 
  static MaybeLocal<WasmModuleObject> FromCompiledModule(
      Isolate* isolate, const CompiledWasmModule&);
 
  CompiledWasmModule GetCompiledModule();
 
  struct CompileOptions {
    // Builtin compile-time imports, mirroring the strings accepted in the
    // `builtins` array of the JS `WebAssembly.Module` constructor options.
    // Combine values with bitwise-or to enable multiple builtins.
    struct Builtins {
      enum {
        kNone = 0,
        kJsString = 1 << 0,  // "js-string"
      };
    };
    // Bitwise-or of `Builtins` values to enable as compile-time imports.
    int builtins = Builtins::kNone;
    // If non-null, enable imported string constants from the named module
    // (e.g. "wasm:js/string-constants"). The string must be null-terminated and
    // remain valid for the duration of the compile call.
    const char* imported_string_constants_module = nullptr;
    // If non-empty, associated with the module's script as its source URL, for
    // use in stack traces and developer tooling. If a script already exists in
    // the isolate for the same module, its existing URL is retained. The
    // string must remain valid for the duration of the compile call.
    std::string_view source_url = {};
  };
 
  static MaybeLocal<WasmModuleObject> Compile(
      Isolate* isolate, std::span<const uint8_t> wire_bytes);
 
  static MaybeLocal<WasmModuleObject> Compile(
      Isolate* isolate, std::span<const uint8_t> wire_bytes,
      const CompileOptions& options);
 
  V8_INLINE static WasmModuleObject* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(value);
#endif
    return static_cast<WasmModuleObject*>(value);
  }
 
 private:
  static void CheckCast(Value* obj);
};
 
class V8_EXPORT WasmStreaming final {
 public:
  static constexpr internal::ManagedTypeId kTypeID =
      internal::ManagedTypeId::kWasmStreaming;
  class WasmStreamingImpl;
 
  class ModuleCachingInterface {
   public:
    // Get the full wire bytes, to check against the cached version.
    virtual std::span<const uint8_t> GetWireBytes() const = 0;
    // Pass serialized (cached) compiled module bytes, to be deserialized and
    // used as the result of this streaming compilation.
    // The passed bytes will only be accessed inside this callback, i.e.
    // lifetime can end after the call.
    // The return value indicates whether V8 could use the passed bytes; {false}
    // would be returned on e.g. version mismatch.
    // This method can only be called once.
    virtual bool SetCachedCompiledModuleBytes(std::span<const uint8_t>) = 0;
  };
 
  using ModuleCachingCallback = std::function<void(ModuleCachingInterface&)>;
 
  explicit WasmStreaming(std::unique_ptr<WasmStreamingImpl> impl);
 
  ~WasmStreaming();
 
  void OnBytesReceived(const uint8_t* bytes, size_t size);
 
  void Finish(const ModuleCachingCallback& caching_callback);
 
  void Abort(MaybeLocal<Value> exception);
 
  void SetHasCompiledModuleBytes();
 
  void SetMoreFunctionsCanBeSerializedCallback(
      std::function<void(CompiledWasmModule)>);
 
  /*
   * Sets the UTF-8 encoded source URL for the {Script} object. This must be
   * called before {Finish}.
   */
  void SetUrl(const char* url, size_t length);
 
  static std::shared_ptr<WasmStreaming> Unpack(Isolate* isolate,
                                               Local<Value> value);
 
 private:
  std::unique_ptr<WasmStreamingImpl> impl_;
};
 
class V8_EXPORT WasmModuleCompilation final {
 public:
  using ModuleCachingCallback = WasmStreaming::ModuleCachingCallback;
  using CompileOptions = WasmModuleObject::CompileOptions;
 
  explicit WasmModuleCompilation(const CompileOptions& options = {});
 
  ~WasmModuleCompilation();
 
  WasmModuleCompilation(const WasmModuleCompilation&) = delete;
  WasmModuleCompilation& operator=(const WasmModuleCompilation&) = delete;
 
  void OnBytesReceived(const uint8_t* bytes, size_t size);
 
  void Finish(
      Isolate*, const ModuleCachingCallback& caching_callback,
      const std::function<void(
          std::variant<Local<WasmModuleObject>, Local<Value>> module_or_error)>&
          resolution_callback);
 
  void Abort();
 
  void SetHasCompiledModuleBytes();
 
  void SetMoreFunctionsCanBeSerializedCallback(
      std::function<void(CompiledWasmModule)>);
 
  /*
   * Sets the UTF-8 encoded source URL for the {Script} object. This must be
   * called before {Finish}.
   */
  void SetUrl(const char* url, size_t length);
 
 private:
  class Impl;
  const std::unique_ptr<Impl> impl_;
};
 
class V8_EXPORT WasmMemoryMapDescriptor : public Object {
 public:
  WasmMemoryMapDescriptor() = delete;
 
  using WasmFileDescriptor = SharedMemoryHandle::PlatformHandle;
 
  static Local<WasmMemoryMapDescriptor> New(Isolate* isolate,
                                            WasmFileDescriptor fd);
 
  static bool Unmap(Isolate* isolate, Local<Object> wasm_memory_map_descriptor);
 
  static size_t Map(Isolate* isolate, Local<Object> wasm_memory_map_descriptor,
                    Local<WasmMemoryObject> memory, size_t offset);
};
}  // namespace v8
 
#endif  // INCLUDE_V8_WASM_H_