WebAssembly Web API

本文档建立在 WebAssembly 规范 [WEBASSEMBLY] 和 WebAssembly JavaScript 嵌入 [WASMJS] 之上。

1. 流模块编译和实例化

[Exposed=(Window,Worker)]
partial namespace WebAssembly {
  Promise<Module> compileStreaming(Promise<Response> source);
  Promise<WebAssemblyInstantiatedSource> instantiateStreaming(
      Promise<Response> source, optional object importObject);
};

2. 序列化

Web 用户代理必须使用 [Serializable] 扩展属性来增强 Module 接口。

给定 value、serialized 和 forStorage 的 序列化步骤 为

1. 如果 forStorage 为 true，则抛出 "DataCloneError" DOMException。

2. 将 serialized.[[Bytes]] 设置为 value.[[Bytes]] 的 子序列化。

3. 将 serialized.[[AgentCluster]] 设置为 当前 Realm 对应的 代理集群。

给定 serialized、value 和 targetRealm 的 反序列化步骤 为

1. 令 bytes 为 serialized.[[Bytes]] 的 子反序列化。

2. 将 value.[[Bytes]] 设置为 bytes。

3. 如果 targetRealm 对应的 代理集群 不是 serialized.[[AgentCluster]]，则抛出 "DataCloneError" DOMException。

4. 从 bytes 编译 WebAssembly 模块，并将 value.[[Module]] 设置为结果。

引擎应尝试在执行结构化序列化时共享/重用内部编译的代码，尽管在 CPU 升级或浏览器更新等极端情况下，这可能无法实现，可能需要完全重新编译。

注意： 结构化序列化语义等同于将编译 模块 的二进制源代码序列化，然后反序列化，并重新编译到目标领域。鉴于上述引擎优化，结构化序列化为开发人员提供了对编译代码缓存和跨窗口/工作线程代码共享的显式控制。

3. 面向开发人员的显示约定

本节是非规范性的。

浏览器、JavaScript 引擎和离线工具通常使用相同的方式来引用 JavaScript 工件和语言结构。例如，JavaScript 源代码中的位置在堆栈跟踪或错误消息中打印，并自然地表示为文本文件中的十进制格式行和列。函数和变量的名称直接取自源代码。因此（例如），即使实现相关的堆栈跟踪字符串的确切格式并不总是匹配，但位置很容易理解，并且在不同浏览器中保持一致。

为了实现对 WebAssembly 结构的通用表示的目标，采用了以下约定。

WebAssembly 位置是对二进制文件中特定指令的引用，浏览器或引擎可能在类似于 JavaScript 源代码位置的上下文中显示它。它的格式如下

${url}:wasm-function[${funcIndex}]:${pcOffset}

其中

• ${url} 是与模块关联的 URL（如果适用）（参见注释）。

• ${funcIndex} 是相对于模块的 函数索引。

• ${pcOffset} 是指令第一个字节在模块二进制文件中的偏移量，以十六进制小写数字表示，并以 0x 前缀开头。

注释

• URL 字段的解释可能因上下文而异。当在浏览器中使用基于响应的实例化 API 时，应该使用关联的 URL；或者当使用 ArrayBuffer 基于的实例化 API 时，浏览器应该表示 API 调用的位置。这种实例化类似于使用 eval 执行 JavaScript；因此，如果浏览器有现有的方法来表示 eval 调用的位置，它可以使用类似的方法来表示 WebAssembly.instantiate。例如，如果浏览器对 eval 使用 foo.js line 10 > eval 或 eval at bar (foo.js:10:3)，它可以分别使用 foo.js line 10 > WebAssembly.instantiate 或 WebAssembly.instantiate at bar (foo.js:10:3)。离线工具可以使用文件名代替。

• 使用十六进制表示模块偏移量与 objdump 等原生工具中的常见约定相匹配（地址以十六进制打印），并使其在视觉上与 JavaScript 行号区分开来。其他数字以十进制表示。

虽然 导出函数 实例的 “name” 属性由 JS API 指定，但在其他上下文中（例如调试器中的调用堆栈和堆栈跟踪的字符串表示）也会显示合成函数名称。如果 WebAssembly 模块包含 名称节，则应使用这些名称来合成函数名称，如下所示

• 如果存在函数名称子节，则显示的名称应为 ${module_name}.${function_name} 或 ${function_name}，具体取决于模块名称是否存在。

• 否则，输出可以依赖于上下文

  • 如果函数名称与堆栈跟踪中的位置一起显示，则可以使用模块名称（如果存在）或空字符串（因为函数索引已包含在位置中）。

  • 否则，应使用 ${module_name}.wasm-function[${funcIndex}] 或 wasm-function[${funcIndex}] 来传达函数索引。

请注意，本文件并未指定字符串（例如堆栈帧表示）的完整格式；这允许引擎继续使用其现有的 JavaScript 格式（现有的代码可能已经依赖于它），同时仍然以与 JavaScript 一致的格式打印 WebAssembly 帧。

4. 媒体类型注册

本节将提交给互联网工程指导组 (IESG) 以供审查、批准和向 IANA 注册。

application/wasm

类型名称

application

子类型名称

wasm

必需参数

无

可选参数

无

编码注意事项

binary

安全注意事项

WebAssembly 是一种标准、安全、可移植的低级代码格式。与执行 WebAssembly 代码相关的安全注意事项在 https://www.w3.org/TR/wasm-core/#security-considerations 中描述。

WebAssembly 格式不包括完整性或隐私保护。如果需要此类保护，则必须通过外部方式提供，例如使用 HTTPS。

互操作性注意事项

参见 WebAssembly 核心一致性
https://www.w3.org/TR/wasm-core/#conformance

已发布的规范

https://www.w3.org/TR/wasm-core-1/ https://www.w3.org/TR/wasm-js-api-1/ https://www.w3.org/TR/wasm-web-api-1/

应用程序使用

application/wasm 媒体类型旨在用作描述 WebAssembly 文件的类型，当通过 HTTP 发送到浏览器以供执行时，这是一种常见的情况。此外，该类型由几个 WebAssembly 运行时使用，这些运行时利用安全性并可移植性，同时针对高效执行和紧凑表示。

片段标识符注意事项

无

使用限制

无

临时注册

N/A

其他信息

此类型的弃用别名

无

幻数

0x00 0x61 0x73 0x6D

文件扩展名

.wasm

Macintosh 文件类型代码

无

对象标识符或 OID

无

预期用途

Common

其他信息和注释

Common

联系人

联系人姓名

Eric Prud'hommeaux

联系电子邮件地址

[email protected]

作者/变更控制者

W3C