Loading...
Searching...
No Matches
v8-wasm.h
Go to the documentation of this file.
1// Copyright 2021 the V8 project authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef INCLUDE_V8_WASM_H_
6#define INCLUDE_V8_WASM_H_
7
8#include <functional>
9#include <memory>
10#include <span>
11#include <string>
12#include <string_view>
13#include <utility>
14#include <variant>
15
16#include "v8-internal.h" // NOLINT(build/include_directory)
17#include "v8-local-handle.h" // NOLINT(build/include_directory)
18#include "v8-object.h" // NOLINT(build/include_directory)
19#include "v8-platform.h" // NOLINT(build/include_directory)
20#include "v8config.h" // NOLINT(build/include_directory)
21
22namespace v8 {
23
24class ArrayBufferBase;
25class Promise;
26
27namespace internal::wasm {
28class NativeModule;
29} // namespace internal::wasm
30
35 OwnedBuffer() = default;
36 ~OwnedBuffer() = default;
37
38 OwnedBuffer(const OwnedBuffer&) = delete;
40
41 OwnedBuffer(OwnedBuffer&& other) noexcept
42 : buffer_(std::move(other.buffer_)),
43 size_(std::exchange(other.size_, 0)) {}
44
45 OwnedBuffer& operator=(OwnedBuffer&& other) noexcept {
46 if (this != &other) {
47 buffer_ = std::move(other.buffer_);
48 size_ = std::exchange(other.size_, 0);
49 }
50 return *this;
51 }
52
53 constexpr bool empty() const { return size_ == 0; }
54
55 constexpr std::span<const uint8_t> as_span() const {
56 return {buffer_.get(), size_};
57 }
58
59 private:
60 friend class CompiledWasmModule;
61
62 OwnedBuffer(std::unique_ptr<const uint8_t[]> buffer, size_t size)
63 : buffer_(std::move(buffer)), size_(size) {}
64
65 std::unique_ptr<const uint8_t[]> buffer_;
66 size_t size_ = 0;
67};
68
74 public:
80
84 std::span<const uint8_t> GetWireBytesRef();
85
86 const std::string& source_url() const { return source_url_; }
87
88 private:
90 friend class WasmModuleObject;
91 friend class WasmStreaming;
92
93 explicit CompiledWasmModule(std::shared_ptr<internal::wasm::NativeModule>,
94 std::string source_url);
95
96 const std::shared_ptr<internal::wasm::NativeModule> native_module_;
97 const std::string source_url_;
98};
99
100// An instance of WebAssembly.Memory.
102 public:
104
109
111#ifdef V8_ENABLE_CHECKS
112 CheckCast(value);
113#endif
114 return static_cast<WasmMemoryObject*>(value);
115 }
116
117 private:
118 static void CheckCast(Value* object);
119};
120
121// An instance of WebAssembly.Module.
123 public:
125
131 Isolate* isolate, const CompiledWasmModule&);
132
138
145 // Builtin compile-time imports, mirroring the strings accepted in the
146 // `builtins` array of the JS `WebAssembly.Module` constructor options.
147 // Combine values with bitwise-or to enable multiple builtins.
148 struct Builtins {
149 enum {
150 kNone = 0,
151 kJsString = 1 << 0, // "js-string"
152 };
153 };
154 // Bitwise-or of `Builtins` values to enable as compile-time imports.
155 int builtins = Builtins::kNone;
156 // If non-null, enable imported string constants from the named module
157 // (e.g. "wasm:js/string-constants"). The string must be null-terminated and
158 // remain valid for the duration of the compile call.
159 const char* imported_string_constants_module = nullptr;
160 // If non-empty, associated with the module's script as its source URL, for
161 // use in stack traces and developer tooling. The string must remain valid
162 // for the duration of the compile call.
163 std::string_view source_url = {};
164 };
165
170 Isolate* isolate, std::span<const uint8_t> wire_bytes);
171
177 Isolate* isolate, std::span<const uint8_t> wire_bytes,
178 const CompileOptions& options);
179
181#ifdef V8_ENABLE_CHECKS
182 CheckCast(value);
183#endif
184 return static_cast<WasmModuleObject*>(value);
185 }
186
187 private:
188 static void CheckCast(Value* obj);
189};
190
198 public:
199 static constexpr internal::ManagedTypeId kTypeID =
200 internal::ManagedTypeId::kWasmStreaming;
201 class WasmStreamingImpl;
202
204 public:
205 // Get the full wire bytes, to check against the cached version.
206 virtual std::span<const uint8_t> GetWireBytes() const = 0;
207 // Pass serialized (cached) compiled module bytes, to be deserialized and
208 // used as the result of this streaming compilation.
209 // The passed bytes will only be accessed inside this callback, i.e.
210 // lifetime can end after the call.
211 // The return value indicates whether V8 could use the passed bytes; {false}
212 // would be returned on e.g. version mismatch.
213 // This method can only be called once.
214 virtual bool SetCachedCompiledModuleBytes(std::span<const uint8_t>) = 0;
215 };
216
217 using ModuleCachingCallback = std::function<void(ModuleCachingInterface&)>;
218
219 explicit WasmStreaming(std::unique_ptr<WasmStreamingImpl> impl);
220
222
227 void OnBytesReceived(const uint8_t* bytes, size_t size);
228
238 void Finish(const ModuleCachingCallback& caching_callback);
239
246 void Abort(MaybeLocal<Value> exception);
247
257
263 std::function<void(CompiledWasmModule)>);
264
265 /*
266 * Sets the UTF-8 encoded source URL for the {Script} object. This must be
267 * called before {Finish}.
268 */
269 void SetUrl(const char* url, size_t length);
270
276 static std::shared_ptr<WasmStreaming> Unpack(Isolate* isolate,
277 Local<Data> data);
278
279 private:
280 std::unique_ptr<WasmStreamingImpl> impl_;
281};
282
290 public:
293
300 explicit WasmModuleCompilation(const CompileOptions& options = {});
301
303
306
312 void OnBytesReceived(const uint8_t* bytes, size_t size);
313
326 void Finish(
327 Isolate*, const ModuleCachingCallback& caching_callback,
328 const std::function<void(
329 std::variant<Local<WasmModuleObject>, Local<Value>> module_or_error)>&
330 resolution_callback);
331
336 void Abort();
337
347
353 std::function<void(CompiledWasmModule)>);
354
355 /*
356 * Sets the UTF-8 encoded source URL for the {Script} object. This must be
357 * called before {Finish}.
358 */
359 void SetUrl(const char* url, size_t length);
360
361 private:
362 class Impl;
363 const std::unique_ptr<Impl> impl_;
364};
365
372 public:
374
376
379
380 static bool Unmap(Isolate* isolate, Local<Object> wasm_memory_map_descriptor);
381
382 static size_t Map(Isolate* isolate, Local<Object> wasm_memory_map_descriptor,
383 Local<WasmMemoryObject> memory, size_t offset);
384};
385} // namespace v8
386
387#endif // INCLUDE_V8_WASM_H_
Definition: v8-wasm.h:73
OwnedBuffer Serialize()
const std::string & source_url() const
Definition: v8-wasm.h:86
std::span< const uint8_t > GetWireBytesRef()
Definition: v8-isolate.h:305
Definition: v8-local-handle.h:356
Definition: v8-local-handle.h:724
Definition: v8-object.h:269
int PlatformHandle
Definition: v8-platform.h:500
Definition: v8-value.h:32
Definition: v8-wasm.h:371
static Local< WasmMemoryMapDescriptor > New(Isolate *isolate, WasmFileDescriptor fd)
SharedMemoryHandle::PlatformHandle WasmFileDescriptor
Definition: v8-wasm.h:375
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)
Definition: v8-wasm.h:101
static WasmMemoryObject * Cast(Value *value)
Definition: v8-wasm.h:110
Local< ArrayBufferBase > GetBuffer()
Definition: v8-wasm.h:289
void OnBytesReceived(const uint8_t *bytes, size_t size)
void SetMoreFunctionsCanBeSerializedCallback(std::function< void(CompiledWasmModule)>)
WasmStreaming::ModuleCachingCallback ModuleCachingCallback
Definition: v8-wasm.h:291
WasmModuleCompilation(const WasmModuleCompilation &)=delete
WasmModuleCompilation(const CompileOptions &options={})
void Finish(Isolate *, const ModuleCachingCallback &caching_callback, const std::function< void(std::variant< Local< WasmModuleObject >, Local< Value > > module_or_error)> &resolution_callback)
void SetUrl(const char *url, size_t length)
WasmModuleCompilation & operator=(const WasmModuleCompilation &)=delete
Definition: v8-wasm.h:122
static MaybeLocal< WasmModuleObject > Compile(Isolate *isolate, std::span< const uint8_t > wire_bytes, const CompileOptions &options)
static MaybeLocal< WasmModuleObject > FromCompiledModule(Isolate *isolate, const CompiledWasmModule &)
static MaybeLocal< WasmModuleObject > Compile(Isolate *isolate, std::span< const uint8_t > wire_bytes)
CompiledWasmModule GetCompiledModule()
static WasmModuleObject * Cast(Value *value)
Definition: v8-wasm.h:180
virtual std::span< const uint8_t > GetWireBytes() const =0
virtual bool SetCachedCompiledModuleBytes(std::span< const uint8_t >)=0
Definition: v8-wasm.h:197
std::function< void(ModuleCachingInterface &)> ModuleCachingCallback
Definition: v8-wasm.h:217
WasmStreaming(std::unique_ptr< WasmStreamingImpl > impl)
void Finish(const ModuleCachingCallback &caching_callback)
static std::shared_ptr< WasmStreaming > Unpack(Isolate *isolate, Local< Data > data)
void SetUrl(const char *url, size_t length)
void SetHasCompiledModuleBytes()
void SetMoreFunctionsCanBeSerializedCallback(std::function< void(CompiledWasmModule)>)
void Abort(MaybeLocal< Value > exception)
void OnBytesReceived(const uint8_t *bytes, size_t size)
ManagedTypeId
Definition: v8-internal.h:597
Definition: libplatform.h:15
Definition: v8-wasm.h:34
constexpr bool empty() const
Definition: v8-wasm.h:53
OwnedBuffer()=default
~OwnedBuffer()=default
OwnedBuffer & operator=(OwnedBuffer &&other) noexcept
Definition: v8-wasm.h:45
OwnedBuffer(const OwnedBuffer &)=delete
OwnedBuffer(OwnedBuffer &&other) noexcept
Definition: v8-wasm.h:41
OwnedBuffer & operator=(const OwnedBuffer &)=delete
constexpr std::span< const uint8_t > as_span() const
Definition: v8-wasm.h:55
Definition: v8-wasm.h:144
#define V8_EXPORT
Definition: v8config.h:875
#define V8_INLINE
Definition: v8config.h:519