include/node/v8-wasm.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_WASM_H_
0006 #define INCLUDE_V8_WASM_H_
0007
0008 #include <functional>
0009 #include <memory>
0010 #include <string>
0011
0012 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
0013 #include "v8-memory-span.h"   // NOLINT(build/include_directory)
0014 #include "v8-object.h"        // NOLINT(build/include_directory)
0015 #include "v8config.h"         // NOLINT(build/include_directory)
0016
0017 namespace v8 {
0018
0019 class ArrayBuffer;
0020 class Promise;
0021
0022 namespace internal {
0023 namespace wasm {
0024 class NativeModule;
0025 class StreamingDecoder;
0026 }  // namespace wasm
0027 }  // namespace internal
0028
0029 /**
0030  * An owned byte buffer with associated size.
0031  */
0032 struct OwnedBuffer {
0033   std::unique_ptr<const uint8_t[]> buffer;
0034   size_t size = 0;
0035   OwnedBuffer(std::unique_ptr<const uint8_t[]> buffer, size_t size)
0036       : buffer(std::move(buffer)), size(size) {}
0037   OwnedBuffer() = default;
0038 };
0039
0040 // Wrapper around a compiled WebAssembly module, which is potentially shared by
0041 // different WasmModuleObjects.
0042 class V8_EXPORT CompiledWasmModule {
0043  public:
0044   /**
0045    * Serialize the compiled module. The serialized data does not include the
0046    * wire bytes.
0047    */
0048   OwnedBuffer Serialize();
0049
0050   /**
0051    * Get the (wasm-encoded) wire bytes that were used to compile this module.
0052    */
0053   MemorySpan<const uint8_t> GetWireBytesRef();
0054
0055   const std::string& source_url() const { return source_url_; }
0056
0057  private:
0058   friend class WasmModuleObject;
0059   friend class WasmStreaming;
0060
0061   explicit CompiledWasmModule(std::shared_ptr<internal::wasm::NativeModule>,
0062                               const char* source_url, size_t url_length);
0063
0064   const std::shared_ptr<internal::wasm::NativeModule> native_module_;
0065   const std::string source_url_;
0066 };
0067
0068 // An instance of WebAssembly.Memory.
0069 class V8_EXPORT WasmMemoryObject : public Object {
0070  public:
0071   WasmMemoryObject() = delete;
0072
0073   /**
0074    * Returns underlying ArrayBuffer.
0075    */
0076   Local<ArrayBuffer> Buffer();
0077
0078   V8_INLINE static WasmMemoryObject* Cast(Value* value) {
0079 #ifdef V8_ENABLE_CHECKS
0080     CheckCast(value);
0081 #endif
0082     return static_cast<WasmMemoryObject*>(value);
0083   }
0084
0085  private:
0086   static void CheckCast(Value* object);
0087 };
0088
0089 // An instance of WebAssembly.Module.
0090 class V8_EXPORT WasmModuleObject : public Object {
0091  public:
0092   WasmModuleObject() = delete;
0093
0094   /**
0095    * Efficiently re-create a WasmModuleObject, without recompiling, from
0096    * a CompiledWasmModule.
0097    */
0098   static MaybeLocal<WasmModuleObject> FromCompiledModule(
0099       Isolate* isolate, const CompiledWasmModule&);
0100
0101   /**
0102    * Get the compiled module for this module object. The compiled module can be
0103    * shared by several module objects.
0104    */
0105   CompiledWasmModule GetCompiledModule();
0106
0107   /**
0108    * Compile a Wasm module from the provided uncompiled bytes.
0109    */
0110   static MaybeLocal<WasmModuleObject> Compile(
0111       Isolate* isolate, MemorySpan<const uint8_t> wire_bytes);
0112
0113   V8_INLINE static WasmModuleObject* Cast(Value* value) {
0114 #ifdef V8_ENABLE_CHECKS
0115     CheckCast(value);
0116 #endif
0117     return static_cast<WasmModuleObject*>(value);
0118   }
0119
0120  private:
0121   static void CheckCast(Value* obj);
0122 };
0123
0124 /**
0125  * The V8 interface for WebAssembly streaming compilation. When streaming
0126  * compilation is initiated, V8 passes a {WasmStreaming} object to the embedder
0127  * such that the embedder can pass the input bytes for streaming compilation to
0128  * V8.
0129  */
0130 class V8_EXPORT WasmStreaming final {
0131  public:
0132   class WasmStreamingImpl;
0133
0134   explicit WasmStreaming(std::unique_ptr<WasmStreamingImpl> impl);
0135
0136   ~WasmStreaming();
0137
0138   /**
0139    * Pass a new chunk of bytes to WebAssembly streaming compilation.
0140    * The buffer passed into {OnBytesReceived} is owned by the caller.
0141    */
0142   void OnBytesReceived(const uint8_t* bytes, size_t size);
0143
0144   /**
0145    * {Finish} should be called after all received bytes where passed to
0146    * {OnBytesReceived} to tell V8 that there will be no more bytes. {Finish}
0147    * must not be called after {Abort} has been called already.
0148    * If {can_use_compiled_module} is true and {SetCompiledModuleBytes} was
0149    * previously called, the compiled module bytes can be used.
0150    * If {can_use_compiled_module} is false, the compiled module bytes previously
0151    * set by {SetCompiledModuleBytes} should not be used.
0152    */
0153   void Finish(bool can_use_compiled_module = true);
0154
0155   /**
0156    * Abort streaming compilation. If {exception} has a value, then the promise
0157    * associated with streaming compilation is rejected with that value. If
0158    * {exception} does not have value, the promise does not get rejected.
0159    * {Abort} must not be called repeatedly, or after {Finish}.
0160    */
0161   void Abort(MaybeLocal<Value> exception);
0162
0163   /**
0164    * Passes previously compiled module bytes. This must be called before
0165    * {OnBytesReceived}, {Finish}, or {Abort}. Returns true if the module bytes
0166    * can be used, false otherwise. The buffer passed via {bytes} and {size}
0167    * is owned by the caller. If {SetCompiledModuleBytes} returns true, the
0168    * buffer must remain valid until either {Finish} or {Abort} completes.
0169    * The compiled module bytes should not be used until {Finish(true)} is
0170    * called, because they can be invalidated later by {Finish(false)}.
0171    */
0172   bool SetCompiledModuleBytes(const uint8_t* bytes, size_t size);
0173
0174   /**
0175    * Sets a callback which is called whenever a significant number of new
0176    * functions are ready for serialization.
0177    */
0178   void SetMoreFunctionsCanBeSerializedCallback(
0179       std::function<void(CompiledWasmModule)>);
0180
0181   /*
0182    * Sets the UTF-8 encoded source URL for the {Script} object. This must be
0183    * called before {Finish}.
0184    */
0185   void SetUrl(const char* url, size_t length);
0186
0187   /**
0188    * Unpacks a {WasmStreaming} object wrapped in a  {Managed} for the embedder.
0189    * Since the embedder is on the other side of the API, it cannot unpack the
0190    * {Managed} itself.
0191    */
0192   static std::shared_ptr<WasmStreaming> Unpack(Isolate* isolate,
0193                                                Local<Value> value);
0194
0195  private:
0196   std::unique_ptr<WasmStreamingImpl> impl_;
0197 };
0198
0199 }  // namespace v8
0200
0201 #endif  // INCLUDE_V8_WASM_H_