WebAssembly.instantiate()

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 関数を呼び出します。

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() を使用してワーカーに送信しています。

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

WebAssembly.compileStreaming(fetch('simple.wasm'))
.then(mod =>
  worker.postMessage(mod)
);

ワーカーでは (wasm_worker.jsを参照) モジュールで使用するためのインポートオブジェクトを定義して、メインスレッドからモジュールを受け取るイベントハンドラーを設定し、 WebAssembly.instantiate() メソッドを使用してインスタンスを生成し、エクスポートされた関数を呼び出します。

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();
  });
};

仕様書

仕様書
WebAssembly JavaScript Interface
instantiate() の定義

ブラウザーの互換性

BCD tables only load in the browser

関連情報