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 #include <variant>
0012
0013 #include "v8-internal.h"      // NOLINT(build/include_directory)
0014 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
0015 #include "v8-memory-span.h"   // NOLINT(build/include_directory)
0016 #include "v8-object.h"        // NOLINT(build/include_directory)
0017 #include "v8config.h"         // NOLINT(build/include_directory)
0018
0019 namespace v8 {
0020
0021 class ArrayBuffer;
0022 class Promise;
0023
0024 namespace internal::wasm {
0025 class NativeModule;
0026 }  // namespace internal::wasm
0027
0028 /**
0029  * An owned byte buffer with associated size.
0030  */
0031 struct OwnedBuffer {
0032   std::unique_ptr<const uint8_t[]> buffer;
0033   size_t size = 0;
0034   OwnedBuffer(std::unique_ptr<const uint8_t[]> buffer, size_t size)
0035       : buffer(std::move(buffer)), size(size) {}
0036   OwnedBuffer() = default;
0037 };
0038
0039 /**
0040  * Wrapper around a compiled WebAssembly module, which is potentially shared by
0041  * different WasmModuleObjects.
0042  */
0043 class V8_EXPORT CompiledWasmModule {
0044  public:
0045   /**
0046    * Serialize the compiled module. The serialized data does not include the
0047    * wire bytes.
0048    */
0049   OwnedBuffer Serialize();
0050
0051   /**
0052    * Get the (wasm-encoded) wire bytes that were used to compile this module.
0053    */
0054   MemorySpan<const uint8_t> GetWireBytesRef();
0055
0056   const std::string& source_url() const { return source_url_; }
0057
0058  private:
0059   friend class WasmModuleCompilation;
0060   friend class WasmModuleObject;
0061   friend class WasmStreaming;
0062
0063   explicit CompiledWasmModule(std::shared_ptr<internal::wasm::NativeModule>,
0064                               std::string source_url);
0065
0066   const std::shared_ptr<internal::wasm::NativeModule> native_module_;
0067   const std::string source_url_;
0068 };
0069
0070 // An instance of WebAssembly.Memory.
0071 class V8_EXPORT WasmMemoryObject : public Object {
0072  public:
0073   WasmMemoryObject() = delete;
0074
0075   /**
0076    * Returns underlying ArrayBuffer.
0077    */
0078   Local<ArrayBuffer> Buffer();
0079
0080   V8_INLINE static WasmMemoryObject* Cast(Value* value) {
0081 #ifdef V8_ENABLE_CHECKS
0082     CheckCast(value);
0083 #endif
0084     return static_cast<WasmMemoryObject*>(value);
0085   }
0086
0087  private:
0088   static void CheckCast(Value* object);
0089 };
0090
0091 // An instance of WebAssembly.Module.
0092 class V8_EXPORT WasmModuleObject : public Object {
0093  public:
0094   WasmModuleObject() = delete;
0095
0096   /**
0097    * Efficiently re-create a WasmModuleObject, without recompiling, from
0098    * a CompiledWasmModule.
0099    */
0100   static MaybeLocal<WasmModuleObject> FromCompiledModule(
0101       Isolate* isolate, const CompiledWasmModule&);
0102
0103   /**
0104    * Get the compiled module for this module object. The compiled module can be
0105    * shared by several module objects.
0106    */
0107   CompiledWasmModule GetCompiledModule();
0108
0109   /**
0110    * Compile a Wasm module from the provided uncompiled bytes.
0111    */
0112   static MaybeLocal<WasmModuleObject> Compile(
0113       Isolate* isolate, MemorySpan<const uint8_t> wire_bytes);
0114
0115   V8_INLINE static WasmModuleObject* Cast(Value* value) {
0116 #ifdef V8_ENABLE_CHECKS
0117     CheckCast(value);
0118 #endif
0119     return static_cast<WasmModuleObject*>(value);
0120   }
0121
0122  private:
0123   static void CheckCast(Value* obj);
0124 };
0125
0126 /**
0127  * The V8 interface for WebAssembly streaming compilation. When streaming
0128  * compilation is initiated, V8 passes a {WasmStreaming} object to the embedder
0129  * such that the embedder can pass the input bytes for streaming compilation to
0130  * V8.
0131  */
0132 class V8_EXPORT WasmStreaming final {
0133  public:
0134   static constexpr internal::ExternalPointerTag kManagedTag =
0135       internal::kWasmWasmStreamingTag;
0136   class WasmStreamingImpl;
0137
0138   class ModuleCachingInterface {
0139    public:
0140     // Get the full wire bytes, to check against the cached version.
0141     virtual MemorySpan<const uint8_t> GetWireBytes() const = 0;
0142     // Pass serialized (cached) compiled module bytes, to be deserialized and
0143     // used as the result of this streaming compilation.
0144     // The passed bytes will only be accessed inside this callback, i.e.
0145     // lifetime can end after the call.
0146     // The return value indicates whether V8 could use the passed bytes; {false}
0147     // would be returned on e.g. version mismatch.
0148     // This method can only be called once.
0149     virtual bool SetCachedCompiledModuleBytes(MemorySpan<const uint8_t>) = 0;
0150   };
0151
0152   using ModuleCachingCallback = std::function<void(ModuleCachingInterface&)>;
0153
0154   explicit WasmStreaming(std::unique_ptr<WasmStreamingImpl> impl);
0155
0156   ~WasmStreaming();
0157
0158   /**
0159    * Pass a new chunk of bytes to WebAssembly streaming compilation.
0160    * The buffer passed into {OnBytesReceived} is owned by the caller.
0161    */
0162   void OnBytesReceived(const uint8_t* bytes, size_t size);
0163
0164   /**
0165    * {Finish} should be called after all received bytes where passed to
0166    * {OnBytesReceived} to tell V8 that there will be no more bytes. {Finish}
0167    * must not be called after {Abort} has been called already.
0168    * If {SetHasCompiledModuleBytes()} was called before, a {caching_callback}
0169    * can be passed which can inspect the full received wire bytes and set cached
0170    * module bytes which will be deserialized then. This callback will happen
0171    * synchronously within this call; the callback is not stored.
0172    */
0173   void Finish(const ModuleCachingCallback& caching_callback);
0174
0175   /**
0176    * Abort streaming compilation. If {exception} has a value, then the promise
0177    * associated with streaming compilation is rejected with that value. If
0178    * {exception} does not have value, the promise does not get rejected.
0179    * {Abort} must not be called repeatedly, or after {Finish}.
0180    */
0181   void Abort(MaybeLocal<Value> exception);
0182
0183   /**
0184    * Mark that the embedder has (potentially) cached compiled module bytes (i.e.
0185    * a serialized {CompiledWasmModule}) that could match this streaming request.
0186    * This will cause V8 to skip streaming compilation.
0187    * The embedder should then pass a callback to the {Finish} method to pass the
0188    * serialized bytes, after potentially checking their validity against the
0189    * full received wire bytes.
0190    */
0191   void SetHasCompiledModuleBytes();
0192
0193   /**
0194    * Sets a callback which is called whenever a significant number of new
0195    * functions are ready for serialization.
0196    */
0197   void SetMoreFunctionsCanBeSerializedCallback(
0198       std::function<void(CompiledWasmModule)>);
0199
0200   /*
0201    * Sets the UTF-8 encoded source URL for the {Script} object. This must be
0202    * called before {Finish}.
0203    */
0204   void SetUrl(const char* url, size_t length);
0205
0206   /**
0207    * Unpacks a {WasmStreaming} object wrapped in a  {Managed} for the embedder.
0208    * Since the embedder is on the other side of the API, it cannot unpack the
0209    * {Managed} itself.
0210    */
0211   static std::shared_ptr<WasmStreaming> Unpack(Isolate* isolate,
0212                                                Local<Value> value);
0213
0214  private:
0215   std::unique_ptr<WasmStreamingImpl> impl_;
0216 };
0217
0218 /**
0219  * An interface for asynchronous WebAssembly module compilation, to be used e.g.
0220  * for implementing source phase imports.
0221  * Note: This interface is experimental and can change or be removed without
0222  * notice.
0223  */
0224 class V8_EXPORT WasmModuleCompilation final {
0225  public:
0226   using ModuleCachingCallback = WasmStreaming::ModuleCachingCallback;
0227
0228   /**
0229    * Start an asynchronous module compilation. This can be called on any thread.
0230    * TODO(clemensb): Add some way to pass enabled features.
0231    * TODO(clemensb): Add some way to pass compile time imports.
0232    */
0233   WasmModuleCompilation();
0234
0235   ~WasmModuleCompilation();
0236
0237   WasmModuleCompilation(const WasmModuleCompilation&) = delete;
0238   WasmModuleCompilation& operator=(const WasmModuleCompilation&) = delete;
0239
0240   /**
0241    * Pass a new chunk of bytes to WebAssembly compilation.
0242    * The buffer passed into {OnBytesReceived} is owned by the caller and will
0243    * not be accessed any more after this call returns.
0244    */
0245   void OnBytesReceived(const uint8_t* bytes, size_t size);
0246
0247   /**
0248    * {Finish} must be called on the main thread after all bytes were passed to
0249    * {OnBytesReceived}.
0250    * It eventually calls the provided callback to deliver the compiled module or
0251    * an error. This callback will also be called in foreground, but not
0252    * necessarily within this call.
0253    * {Finish} must not be called after {Abort} has been called already.
0254    * If {SetHasCompiledModuleBytes()} was called before, a {caching_callback}
0255    * can be passed which can inspect the full received wire bytes and set cached
0256    * module bytes which will be deserialized then. This callback will happen
0257    * synchronously within this call; the callback is not stored.
0258    */
0259   void Finish(
0260       Isolate*, const ModuleCachingCallback& caching_callback,
0261       const std::function<void(
0262           std::variant<Local<WasmModuleObject>, Local<Value>> module_or_error)>&
0263           resolution_callback);
0264
0265   /**
0266    * Abort compilation. This can be called from any thread.
0267    * {Abort} must not be called repeatedly, or after {Finish}.
0268    */
0269   void Abort();
0270
0271   /**
0272    * Mark that the embedder has (potentially) cached compiled module bytes (i.e.
0273    * a serialized {CompiledWasmModule}) that could match this streaming request.
0274    * This will cause V8 to skip streaming compilation.
0275    * The embedder should then pass a callback to the {Finish} method to pass the
0276    * serialized bytes, after potentially checking their validity against the
0277    * full received wire bytes.
0278    */
0279   void SetHasCompiledModuleBytes();
0280
0281   /**
0282    * Sets a callback which is called whenever a significant number of new
0283    * functions are ready for serialization.
0284    */
0285   void SetMoreFunctionsCanBeSerializedCallback(
0286       std::function<void(CompiledWasmModule)>);
0287
0288   /*
0289    * Sets the UTF-8 encoded source URL for the {Script} object. This must be
0290    * called before {Finish}.
0291    */
0292   void SetUrl(const char* url, size_t length);
0293
0294  private:
0295   class Impl;
0296   const std::unique_ptr<Impl> impl_;
0297 };
0298
0299 /**
0300  * The V8 interface for a WebAssembly memory map descriptor. This is an
0301  * experimental feature that may change and be removed without further
0302  * communication.
0303  */
0304 class V8_EXPORT WasmMemoryMapDescriptor : public Object {
0305  public:
0306   WasmMemoryMapDescriptor() = delete;
0307
0308   V8_INLINE static WasmMemoryMapDescriptor* Cast(Value* value) {
0309 #ifdef V8_ENABLE_CHECKS
0310     CheckCast(value);
0311 #endif
0312     return static_cast<WasmMemoryMapDescriptor*>(value);
0313   }
0314
0315   using WasmFileDescriptor = int32_t;
0316
0317   static Local<WasmMemoryMapDescriptor> New(Isolate* isolate,
0318                                             WasmFileDescriptor fd);
0319
0320  private:
0321   static void CheckCast(Value* object);
0322 };
0323 }  // namespace v8
0324
0325 #endif  // INCLUDE_V8_WASM_H_