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 コードをコンパイルおよびインスタンス化することができます。この関数は 2 つのオーバーロードを持ちます。

  • 第一のオーバーロードは、 型付き配列 または ArrayBuffer で表現された WebAssembly バイナリーコードを受け取り、そして、コンパイルとインスタンス化の両方を 1 ステップで行います。返された Promise は解決時にコンパイルされた WebAssembly.Module と最初の WebAssembly.Instance を渡します。
  • 第二のオーバーロードは、すでにコンパイルされた WebAssembly.Module を受け取り、解決時にその ModuleInstance を渡す Promise を返します。このオーバーロードは、すでに Module がコンパイル済みの場合に有用です。

警告: このメソッドは wasm モジュールの読み込みとインスタンス化に最も効率的な方法ではありません。可能であれば、代わりにもっと新しい WebAssembly.instantiateStreaming() メソッドを使用すれば、生のバイトコードから直接モジュールの読み込み、コンパイル、インスタンス化を 1 ステップで行うことができ、 ArrayBuffer へ変換する必要がありません。

構文

第一のオーバーロード — wasm バイナリーコード

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

引数

bufferSource

コンパイルする .wasm モジュールを含む 型付き配列 または ArrayBuffer

importObject 省略可

関数や WebAssembly.Memory オブジェクトなどの新しく生成される Instance にインポートされる値を持つオブジェクト。モジュール内で宣言されたインポートそれぞれに対応するプロパティが存在する必要があります。そうでない場合、 WebAssembly.LinkError がスローされます。

返値

解決時に次の 2 つのフィールドを持つ ResultObject を渡す Promise

例外

第二のオーバーロード — モジュールオブジェクトのインスタンスを取る

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

引数

module

インスタンス化する WebAssembly.Module オブジェクト。

importObject 省略可

関数や WebAssembly.Memory オブジェクトなどの新しく生成される Instance にインポートされる値を含むオブジェクト。宣言されたモジュールのインポートごとに 1 つの一致するプロパティが存在する必要があります。そうでない場合、 WebAssembly.LinkError がスローされます。

返値

解決時に WebAssembly.Instance オブジェクトを渡す Promise

例外

: おそらく多くの場合は WebAssembly.instantiateStreaming() を使用したほうが、 instantiate() よりも効率的でしょう。

第一のオーバーロードの例

fetch を使用して WebAssembly バイトコードを読み込んだ後、 WebAssembly.instantiate() 関数を使用してモジュールをコンパイル、インスタンス化し、その処理中に JavaScript の関数を WebAssembly モジュールにインポートします。次に、 Instance によってエクスポートされたエクスポート済み WebAssembly 関数を呼び出します。

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

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

メモ: この例は Github 上の index.html でも見ることができます (動作例)。

第二のオーバーロードの例

次の例 (GitHub 上の index-compile.html デモを参照、 そして 動作例 も確認してください) では、読み込まれた simple.wasm バイトコードを WebAssembly.compileStreaming() メソッドを使用してコンパイルし、 postMessage() を使用してワーカーに送信しています。

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

WebAssembly.compileStreaming(fetch("simple.wasm")).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

関連情報