WebAssembly.instantiate()

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

引数

bufferSource

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

importObject 省略可

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

返値

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

• module: コンパイルされた WebAssembly.Module オブジェクト。この Module は再度インスタンス化することや、 postMessage() 経由で共有したり、 IndexedDB にキャッシュすることができます。
• instance: WebAssembly.Instance オブジェクトで、すべての エクスポートされた WebAssembly 関数 を含む。

例外

• いずれかの引数が正しい型、または構造でない場合、 TypeError がスローされます。
• 失敗した場合、プロミスは失敗の原因に応じて WebAssembly.CompileError, WebAssembly.LinkError, WebAssembly.RuntimeError をもって棄却されます。

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

引数

module

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

importObject 省略可

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

返値

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

例外

• いずれかの引数が正しくない型や構造のオブジェクトの場合、 TypeError がスローされます。
• 失敗した場合、プロミスは失敗の原因に応じて WebAssembly.CompileError, WebAssembly.LinkError, WebAssembly.RuntimeError をもって棄却されます。

注: おそらく多くの場合は 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-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 概要ページ
• WebAssembly の概念
• WebAssembly JavaScript API の使用