モジュールオブジェクト¶

Module は、Emscripten によって生成されたコードが実行中に様々な時点で呼び出す属性を持つグローバル JavaScript オブジェクトです。

開発者は、コードの実行を制御するために Module の実装を提供できます。たとえば、Emscripten からの通知メッセージの表示方法を定義するには、開発者は Module.print 属性を実装します。

Emscripten アプリケーションは起動時に Module オブジェクトの値を確認して適用します。起動 *後* に値を変更しても、一般的には機能しないことに注意してください。ASSERTIONS が有効になっているビルドでは、その場合にエラーが発生します。

注記

Module は、安全な方法で Emscripten API 関数（たとえば ccall()）へのアクセスを提供するためにも使用されます。エクスポートされた関数またはランタイムメソッド（コンパイルされた関数には EXPORTED_FUNCTIONS、ccall などのランタイムメソッドには EXPORTED_RUNTIME_METHODS を使用）は、Module オブジェクトでアクセスできます。ミニファイによって名前が変更されることはなく、オプティマイザは関数が存在することを確認し（未使用として削除しません）。関連する FAQ エントリを参照してください。

モジュールオブジェクトの作成
コンパイル設定
実行への影響
その他のメソッド

モジュールオブジェクトの作成 ¶

emcc の pre-js オプションを使用して、必要な動作で Module オブジェクトを定義（または拡張）する JavaScript コードを追加します。

JavaScript のみ（HTML とは対照的に）を生成する場合、デフォルトでは Module オブジェクトは作成されず、動作は完全に開発者によって定義されます。たとえば、次のコードで Module オブジェクトを作成すると、プログラムからのすべての通知が alert() の呼び出しになります。

var Module = {
  'print': function(text) { alert('stdout: ' + text) },
  'printErr': function(text) { alert('stderr: ' + text) }
};

重要

コードで Closure Compiler を実行する場合（これはオプションであり、--closure 1 で実行できます）、上記の例のように Module のプロパティを引用符で囲む必要があります。さらに、Module の宣言とともにコンパイルされたコードで closure を実行する必要があります。これは --pre-js ファイルに対して自動的に行われます。

HTML を生成する場合、Emscripten はデフォルトのメソッドを使用して Module オブジェクトを作成します（src/shell.html を参照）。この場合も --pre-js を使用する必要がありますが、今回は *既存の* Module オブジェクトにプロパティを追加します。たとえば、次のようにします。

Module['print'] = function(text) { alert('stdout: ' + text) };

Module オブジェクトがメインの JavaScript ファイルによって受信されると、その時点で Module['print'] などが検索され、それに応じて使用されることに注意してください。後で値を変更しても、気付かれない場合があります。

コンパイル設定 ¶

INCOMING_MODULE_JS_API コンパイラ設定は、出力される JS でサポートされる Module 属性を制御します。このリストには、デフォルトで一般的に使用されるものが含まれています。

これをアプリケーションの最小限のリストに設定すると、JS コードサイズが節約されます。たとえば、Module 属性を使用しない場合は、-sINCOMING_MODULE_JS_API=[] でビルドできます。または、少数の属性のみを使用する場合は、-sINCOMING_MODULE_JS_API=print,printErr のようにリストすることができます。

実行への影響 ¶

次の Module 属性は、コードの実行に影響します。動作をカスタマイズするには、これらを設定します。

Module.arguments¶: コマンドライン引数。arguments の値には、コンパイルされたコードが argc と argv をチェックした場合に返される値が含まれます。

Module.buffer¶: メモリとして使用する独自の ArrayBuffer または SharedArrayBuffer を提供できます。

注記

これは、-sWASM=0 の場合にのみサポートされます。WebAssembly のサポートについては、Module.wasmMemory を参照してください。

Module.wasmMemory¶

メモリとして使用する独自の WebAssembly.Memory を提供できます。メモリを初期化するために使用されるプロパティは、コンパイラオプションと一致する必要があります。

たとえば、メモリを増加させずに INITIAL_MEMORY を 8MB に設定した場合、提供する wasmMemory （存在する場合）は 'initial' と 'maximum' の両方を 128 に設定する必要があります（WASM ページサイズは 64KB であるため）。

Module.locateFile¶

設定されている場合、このメソッドは、ランタイムが .wasm WebAssembly ファイル、.mem メモリ初期化ファイル、またはファイルパッケージャーによって生成されたファイルなどのファイルをロードする必要があるときに呼び出されます。関数は、ビルドプロセスで設定されたファイルへの相対パスと prefix （メインの JavaScript ファイルのディレクトリへのパス）を受け取り、実際の URL を返す必要があります。これにより、たとえば CDN でホストする場合など、ファイルパッケージまたは .mem ファイルなどを JavaScript ファイルのディレクトリ（デフォルトの期待値）とは異なる場所にホストできます。

注記

メインの JavaScript をロードする前に locateFile が呼び出された場合、prefix は空の文字列になる可能性があります。たとえば、ファイルパッケージまたはメモリ初期化ファイルが事前にロードされている場合（おそらく HTML から、メインの JavaScript をロードする前）、これが発生する可能性があります。

注記

いくつかの Module.*PrefixURL オプションは locateFile のために廃止されました。これには、memoryInitializerPrefixURL、pthreadMainPrefixURL、cdInitializerPrefixURL、filePackagePrefixURL が含まれます。コードを更新するには、たとえば Module.memoryInitializerPrefixURL を "https://mycdn.com/memory-init-dir/" と等しく使用した場合、次のように置き換えることができます。

Module['locateFile'] = function(path, prefix) {
  // if it's a mem init file, use a custom dir
  if (path.endsWith(".mem")) return "https://mycdn.com/memory-init-dir/" + path;
  // otherwise, use the default, the prefix (JS file's dir) + the path
  return prefix + path;
}

Module.logReadFiles¶: 設定されている場合、ファイルが読み取られると stderr にログが記録されます。

Module.printWithColors¶

Emscripten ランタイムライブラリが色付きで印刷しようとするかどうかを制御します。現在、これはサニタイザーにのみ影響します。

設定されていない場合、node を使用して端末に出力する場合、色が有効になります。

true に設定されている場合、可能な場合は常に色が使用されます。false に設定されている場合、色は使用されません。

Module.onAbort¶: 設定されている場合、この関数はプログラムが異常終了したときに呼び出されます。これは、Cメソッド abort() が直接呼び出された場合、JavaScriptから呼び出された場合、または起動時に必要なファイル（Wasmバイナリなど）を取得できないなどの致命的な問題が原因で発生する可能性があります。この関数を呼び出した後、プログラムは終了します（つまり、停止する代わりに何か他のことをしようと試みるためにこれを使用することはできません。ここでは回復の可能性はありません）。

Module.onRuntimeInitialized¶: 設定されている場合、この関数はランタイムが完全に初期化されたときに呼び出されます。つまり、コンパイルされたコードが安全に実行できる状態になったときです。これは、非同期スタートアップ操作（非同期WebAssemblyコンパイル、ファイルプリロードなど）が完了した後です。（これが呼び出されるのを待つ代わりに、main() が呼び出されるのを待つこともできます。）

Module.noExitRuntime¶: noExitRuntime が true に設定されている場合、run の完了後にランタイムはシャットダウンされません。ランタイムのシャットダウンは、シャットダウンコールバック（たとえば、atexit 呼び出し）を呼び出します。run() の終了後にコードの使用を継続する場合は、これを設定する必要があります。これは、ランタイムをシャットダウンしたくないことを意味するAPIコマンド（たとえば、emscripten_set_main_loop）を使用する場合、自動的に設定されます。

Module.noInitialRun¶: noInitialRun が true に設定されている場合、main() は自動的に呼び出されません（後で自分で呼び出すことができます）。プログラムは、グローバル初期化子、メモリ初期化のセットアップなどは引き続き呼び出します。

Module.preInit¶: グローバル初期化子が実行される前、しかしJavaScriptランタイムの基本的な初期化の後に呼び出される必要がある関数（または関数の配列）。これは通常、ファイルシステム操作に使用されます。

Module.preinitializedWebGLContext¶: -sGL_PREINITIALIZED_CONTEXT を設定してビルドする場合、Module.preinitializedWebGLContext を、事前に作成されたWebGLコンテキストのインスタンスに設定できます。これは、後でC/C++側でWebGLを初期化するときに使用されます。GLコンテキストを事前に作成すると、GL側の読み込み（シェーダーのコンパイル、テクスチャの読み込みなど）を他のページの起動アクションと並行して実行する場合や、コンパイルされたコードを読み込む前または並行して、ページのWebGL機能のサポート（GLバージョンや圧縮テクスチャのサポートなど）を事前に検出する場合に役立ちます。

Module.preRun¶: run() を呼び出す直前、しかしグローバル初期化子を含む環境を定義して設定した後に呼び出す関数の配列。これは、たとえば、ファイルシステムAPI を使用してディレクトリとファイルを設定する場合に役立ちます。これは、ファイルシステムAPIがロードされた後、プログラムが実行を開始する前に発生する必要があるためです。

注記

コードがグローバル初期化子に影響を与える必要がある場合は、代わりに preInit を使用して実行する必要があります。

Module.print¶: 標準出力（stdout）に何かが出力されたときに呼び出されます

Module.printErr¶: 標準エラー出力（stderr）に何かが出力されたときに呼び出されます

Module.mainScriptUrlOrBlob¶: pthreadワーカーまたはWASMワーカーが、メインアプリケーションモジュールJavaScriptファイル（例：main.js）をURLまたはblobから独立してロードできるようにします。pthreadワーカーまたはWASMワーカーの作成では、メインアプリケーションモジュールJavaScriptファイル（例：main.js）を読み込む必要があります。デフォルトでは、main.jsのURLからmain.jsの内容を読み込みます。ただし、main.jsファイルがBlobからロードされた場合、main.jsのURLにアクセスすることはできません。また、main.jsがNode.JSモジュールバンドラー（例：webpack）によってバンドルされている場合、そのスクリプトのURLが間違っている可能性があり、webpackバンドラー後のURLはmain.chunk.jsのような間違ったURLになります

その他のメソッド ¶

Module.destroy(obj)¶

このメソッドは、WebIDLバインディングを使用してJavaScriptで作成されたC++オブジェクトを破棄するために呼び出す必要があります。このメソッドが呼び出されない場合、オブジェクトはガベージコレクションされる可能性がありますが、そのデストラクタは呼び出されません。

引数

obj – 破棄されるJavaScriptでラップされたC++オブジェクト。

Module.getPreloadedPackage()¶: カスタムキャッシュ、進捗レポート、エラー処理動作のために.dataファイルパッケージのダウンロードを手動で管理する場合は、Module.getPreloadedPackage = function(remotePackageName, remotePackageSize) コールバックを実装して、データファイルの内容をファイルロードスクリプトに返すことができます。このコールバックの戻り値は、ダウンロードされたファイルデータの内容を含むArraybufferである必要があります。ファイル test/manual_download_data.html とテスト browser.test_preload_file_with_manual_data_download を例として参照してください。

Module.instantiateWasm()¶

WebAssemblyをターゲットとする場合、Module.instantiateWasmは、EmscriptenランタイムがWebAssemblyインスタンス化アクションを実行するために呼び出す、オプションのユーザー実装コールバック関数です。コールバック関数は、imports と successCallback の2つのパラメーターで呼び出されます。imports は、インスタンス化時にWebAssemblyモジュールに渡す必要があるすべての関数インポートを含むJSオブジェクトであり、インスタンス化が完了したら、このコールバック関数は、生成されたWebAssemblyインスタンスオブジェクトを使用して successCallback() を呼び出す必要があります。

インスタンス化は、同期または非同期のいずれかで行うことができます。この関数の戻り値には、インスタンス化されたWebAssemblyモジュールの exports オブジェクト、またはインスタンス化が非同期で実行された場合は空の辞書オブジェクト {}、インスタンス化に失敗した場合は false が含まれている必要があります。

この関数を使用してWebAssemblyインスタンス化手順をオーバーライドすると、WebAssemblyのコンパイルと並行して実行できる他のカスタム非同期スタートアップアクションまたはダウンロードがある場合に役立ちます。このコールバックを実装することで、これらすべてを並行して実行できます。ファイル test/manual_wasm_instantiate.html とテスト browser.test_manual_wasm_instantiate を参照して、この構造が実際にどのように機能するかを確認してください。

注記

Module.instantiateWasmでWebAssemblyインスタンス化をオーバーライドする場合、サニタイザーまたはソースマップは現在サポートされていません。ソースマップまたはサニタイザーが有効になっている場合にModule.instantiateWasmを提供すると、WebAssemblyインスタンス化が完了しない可能性があります。

Module.onCustomMessage()¶: PROXY_TO_WORKER = 1 でコンパイルする場合（settings.js を参照）、このコールバック（クライアントとワーカーの両方の Module オブジェクトに実装する必要があります）により、Webワーカーとメインスレッド間でカスタムメッセージとデータを送信できます（proxyClient.js および proxyWorker.js で定義されている postCustomMessage 関数を使用）。

Module.fetchSettings()¶: ネットワークからWasmモジュールを取得するときに使用されるデフォルトの設定オブジェクトをオーバーライドします。この属性は文字列である必要があり、デフォルトは { credentials: 'same-origin' } です。

モジュールオブジェクト¶

モジュールオブジェクトの作成¶

コンパイル設定¶

実行への影響¶

その他のメソッド¶

モジュールオブジェクトの作成 ¶

コンパイル設定 ¶

実行への影響 ¶

その他のメソッド ¶