WebAssembly.instantiate()

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since October 2017.

* Some parts of this feature may have varying levels of support.

WebAssembly.instantiate() 允许你编译和实例化 WebAssembly 代码。这个方法有两个重载方式:

  • 第一种主要重载方式使用 WebAssembly 二进制代码的 typed arrayArrayBuffer形,一并进行编译和实例化。返回的 Promise 会携带已编译的 WebAssembly.Module 和它的第一个实例化对象 WebAssembly.Instance.
  • 第二种重载使用已编译的 WebAssembly.Module , 返回的 Promise 携带一个 Module的实例化对象 Instance. 如果这个 Module 已经被编译了或者是从缓存中获取的 ( retrieved from cache), 那么这种重载方式是非常有用的。

警告: 此方法不是获取 (fetch) 和实例化 wasm 模块的最具效率方法。如果可能的话,你应该改用较新的WebAssembly.instantiateStreaming()方法,该方法直接从原始字节码中直接获取,编译和实例化模块,因此不需要转换为ArrayBuffer

语法

主重载方式 — 使用 wasm 二进制代码

Promise<ResultObject> WebAssembly.instantiate(bufferSource, importObject);

参数

bufferSource

一个包含你想编译的 wasm 模块二进制代码的 typed array(类型数组) or ArrayBuffer(数组缓冲区)

importObject 可选

一个将被导入到新创建实例中的对象,它包含的值有函数、WebAssembly.Memory 对象等等。编译的模块中,对于每一个导入的值都要有一个与其匹配的属性与之相对应,否则将会抛出 WebAssembly.LinkError

返回值

解析为包含两个字段的 ResultObject 的一个 Promise:

异常

第二种重载 — 使用模块对象

Promise<WebAssembly.Instance> WebAssembly.instantiate(module, importObject);

参数

module

将被实例化的 WebAssembly.Module 对象。

importObject 可选

一个将被导入到新创建实例中的对象,它包含的值有函数、WebAssembly.Memory 对象等等。编译的模块中,对于每一个导入的值都要有一个与其匹配的属性与之相对应,否则将会抛出WebAssembly.LinkError

返回值

一个解析为 WebAssembly.InstancePromise 对象。

异常

示例

备注: 在大多数情况下,你可能需要使用 WebAssembly.instantiateStreaming(),因为它比 instantiate() 更具效率。

第一种重载示例

使用 fetch 获取一些 WebAssembly 二进制代码后,我们使用 WebAssembly.instantiate() 方法编译并实例化模块,在此过程中,导入了一个 Javascript 方法在 WebAssembly 模块中,接下来我们使用Instance 导出的 Exported WebAssembly 方法。

js
var importObject = {
  imports: {
    imported_func: function (arg) {
      console.log(arg);
    },
  },
  env: {
    abort: () => {},
  },
};

/* 2019-08-03:importObject 必须存在 env 对象以及 env 对象的 abort 方法 */

fetch("simple.wasm")
  .then((response) => response.arrayBuffer())
  .then((bytes) => WebAssembly.instantiate(bytes, importObject))
  .then((result) => result.instance.exports);

备注: 查看 GitHub(在线实例)的 index.html 中一个相似的例子。

第二种重载示例

下面的例子(查看我们 GitHub 的 index-compile.html 例子,可在线演示)使用 compile() 方法编译了 simple.wasm 字节码,然后通过 postMessage() 发送给一个线程 worker

js
var worker = new Worker("wasm_worker.js");

fetch("simple.wasm")
  .then((response) => response.arrayBuffer())
  .then((bytes) => WebAssembly.compile(bytes))
  .then((mod) => worker.postMessage(mod));

在线程中(查看 wasm_worker.js)我们定义了一个导入对象供模块使用,然后设置了一个事件处理函数来接收主线程发来的模块。当模块被接收到后,我们使用WebAssembly.instantiate() 方法创建一个实例并且调用它从内部导出的函数。

js
var importObject = {
  imports: {
    imported_func: function (arg) {
      console.log(arg);
    },
  },
};

onmessage = function (e) {
  console.log("module received from main thread");
  var mod = e.data;

  WebAssembly.instantiate(mod, importObject).then(function (instance) {
    instance.exports.exported_func();
  });
};

规范

Specification
WebAssembly JavaScript Interface
# dom-webassembly-instantiate

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
instantiate() static method
compileOptions parameter

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support

参见